notebooks/git_merge_conflicts.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "0ff7b136",
   "metadata": {},
   "source": [
    "# Exercise notebook: Git merge conflicts\n",
    "\n",
    "[![Offered at: Otto-Friedrich-Universität Bamberg](https://img.shields.io/badge/Offered%20by-the%20Digital%20Work%20Lab%20(Otto--Friedrich--Universit%C3%A4t%20Bamberg)-blue)](https://digital-work-lab.github.io/open-source-project/)\n",
    "![License: CC BY 4.0](https://img.shields.io/badge/License-CC%20BY%204.0-green.svg)\n",
    "\n",
    "<img src=\"img/iconmonstr-certificate-6.svg\" alt=\"Edit\" width=\"16\" height=\"16\">  The notebook builds on our peer-reviewed <a href=\"iconmonstr-certificate-6.svg\">pedagogical foundations</a>.\n",
    "\n",
    "We  <img src=\"img/iconmonstr-favorite-2.svg\" alt=\"Edit\" width=\"12\" height=\"12\">  your <a href=\"https://github.com/digital-work-lab/practice-git/issues/new/choose\" target=\"_blank\">feedback</a> and <a href=\"https://github.com/digital-work-lab/practice-git/edit/main/notebooks/git_merge_conflicts.ipynb\" target=\"_blank\">suggestions</a> on this notebook!\n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a8a20b4e",
   "metadata": {},
   "source": [
    "<div style=\"border-left: 4px solid #026e57; background-color: #d0f0e4; padding: 15px; margin: 10px 0; color: #026e57; border-radius: 5px; width:800px;\">\n",
    "    <strong>Transfer Challenge</strong>: Git merges occur when two branches are integrated. Merge conflicts require you to resolve competing file changes. <br>\n",
    "</div>\n",
    "\n",
    "<br>\n",
    "\n",
    "With this notebook, you can practice merging and resolving merge conflicts.\n",
    "\n",
    "| Practice | Label                                                   | Time (min) |\n",
    "|----------|---------------------------------------------------------|------------|\n",
    "|  1       | [A simple merge conflict](#simple)                      | 20         |\n",
    "|  2       | Optional: [A more realistic merge conflict](#realistic) | 30         |\n",
    "|  3       | [Understand how to prevent merge conflicts](#prevent)   |  8         |\n",
    "|  4       | [Wrap-up](#wrap-up)                                     |  2         |\n",
    "|          | Overall                                                 | 40         |\n",
    "\n",
    "<img src=\"img/iconmonstr-help-6.svg\" alt=\"Edit\" width=\"12\" height=\"12\"> We are here to help if errors or questions come up!\n",
    "\n",
    "<br>\n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "df3855cd",
   "metadata": {},
   "source": [
    "<div style=\"border: 2px solid #ff9800; padding: 10px; background-color: #ffe0b2; color: #e65100; border-radius: 5px; display: inline-block; width: fit-content; width:800px;\">\n",
    "    <strong>Important:</strong> Make sure to copy the commands and enter them in the shell as shown in the screenshot. It is not possible to run the cells in this notebook.\n",
    "    <div style=\"clear: both;\"></div>\n",
    "    <img src=\"img/codespace-shell.png\" width=\"800\"/>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "06291aa5",
   "metadata": {},
   "source": [
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify;\">Git is highly efficient in creating branches and merging them. This is a useful property for software development projects in which programmers implement different features, fix bugs, and refactor the codebase. These changes are typically implemented in separate branches, which are not affected by coding activities in other parts of the codebase (other branches). When developers decide that the work from their branch should be integrated into a target branch (often the main branch), the <code>git merge other_branch_name</code> command starts the merge operation. In this operation, Git uses heuristics to determine whether the changes in both branches are compatible. When developers have changed unrelated parts of the codebase, the branches are merged automatically.</p>\n",
    "\n",
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify;\">However, if the branches introduce changes to the same parts of the codebase, there is no simple rule to decide which change is kept and which is discarded. In this case, Git creates a <b>merge conflict</b>, indicating that the user has to indicate which changes should be retained.</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "385a3c53",
   "metadata": {},
   "source": [
    "## Part 1: Resolving a simple merge conflict <a id=\"simple\"></a>\n",
    "\n",
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\">To create and resolve a merge conflict in a simple hello-world project, run the following commands in the (GitHub Codespace) shell below:</p>\n",
    "\n",
    "<div style=\"border: 2px solid #03a9f4; padding: 10px; background-color: #b3e5fc; color: #01579b; border-radius: 5px; display: inline-block; width: fit-content;  width: 800px;\">\n",
    "    <strong>Info</strong> The last command will reopen the codespace window and add the new project to the explorer sidebar. You will have to navigate to this notebook again.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e164459d",
   "metadata": {},
   "outputs": [],
   "source": [
    "cd /workspaces\n",
    "mkdir project\n",
    "cd project\n",
    "git init\n",
    "echo \"print('hello world')\" > app.py\n",
    "git add app.py\n",
    "git commit -m 'first commit'\n",
    "code -a /workspaces/project"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\">At this point, the Python script printing a \"hello world\" statement should be saved in the <code>app.py</code> file and included in the first commit.</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "45fd231e",
   "metadata": {},
   "source": [
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\">We will proceed to create and resolve a merge conflict. Two developers will help us: Linda and Reynold. Each modifies the file to print something different. Let's start with Reynold.</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "95881679",
   "metadata": {},
   "outputs": [],
   "source": [
    "cd /workspaces/project\n",
    "git branch bugfix\n",
    "git switch bugfix\n",
    "echo \"print('hello world. good luck with this shity day and all the rain.')\" > app.py\n",
    "git add app.py\n",
    "git commit -m 'use a more accurate greeting'"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c107ba8f",
   "metadata": {},
   "source": [
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\">Next, let's see Linda's contribution.</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e589f227",
   "metadata": {},
   "outputs": [],
   "source": [
    "git switch main\n",
    "echo \"print('hello world. what a beautiful day')\" > app.py\n",
    "git add app.py\n",
    "git commit -m 'include a nice greeting'"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7957d01c",
   "metadata": {},
   "source": [
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\">Given that both have modified the same part of the codebase, we expect a merge conflict.</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ddcafef6",
   "metadata": {},
   "outputs": [],
   "source": [
    "git merge bugfix"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d04c64a3",
   "metadata": {},
   "source": [
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\">Git should now print the following:</p>\n",
    "\n",
    "```bash\n",
    "Auto-merging app.py\n",
    "CONFLICT (add/add): Merge conflict in app.py\n",
    "Automatic merge failed; fix conflicts and then commit the result.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bb1db32e",
   "metadata": {},
   "source": [
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\">To analyze and resolve the conflict, open the <code>app.py</code> file (VisualStudio highlights files with merge conflicts in red). It should highlight the conflicting part as follows:</p>\n",
    "\n",
    "![Conflict](img/conflict.png)\n",
    "\n",
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\">Note that there are two areas between the <code><<<<<</code>, the <code>=====</code> and the <code>>>>>>>></code> (the conflict markers).</p>\n",
    "\n",
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\">The first section shows the content on your current branch (selected by <code>HEAD</code>). The second section shows the content from the other branch (in this case, <code>bugfix</code>).</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "986fd402",
   "metadata": {},
   "source": [
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\"><b>Task</b>: To resolve the conflict, select the code parts that should be retained. Remove the surrounding conflict markers. Once completed, complete the merge.</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3a5bce96",
   "metadata": {},
   "outputs": [],
   "source": [
    "git add app.py\n",
    "git commit"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a30e798d",
   "metadata": {},
   "source": [
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\">To complete the commit, simply close the commit message.</p>\n",
    "\n",
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\">Check the Git history and verify whether the merge commit was created.</p>\n",
    "\n",
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\">🎉🎈 With these commands, you have solved the first merge conflict! 🎈🎉</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "18f6a83d",
   "metadata": {},
   "source": [
    "## Part 2: Resolving a more realistic merge conflict  <a id=\"realistic\"></a>\n",
    "\n",
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\">For this task, we focus on a project where Lisa and Ted work on a Python module for a comand-line application. Lisa works on a separate branch and changes <code>print()</code> statements to <code>logging.info()</code>. In parallel, Ted introduces changes to the <code>COLORS</code> variable on main. Both changes affect the same module and even the same lines of code. Let's see how the conflict unfolds and how we can resolve it.</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a990f166",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Run these commands if you do not have the colrev project.\n",
    "# git clone https://github.com/CoLRev-Environment/colrev\n",
    "# As you already know, the following will restart your Codespace\n",
    "# code -a /workspaces/colrev\n",
    "# code /workspaces/practice-git/notebooks/git_merge_conflicts.ipynb"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "68b5f01b",
   "metadata": {},
   "outputs": [],
   "source": [
    "cd /workspaces/colrev\n",
    "# Next, we make sure that we always start from the same commit\n",
    "git reset --hard d4b15c1783b48c6a8df04fec165d828709d69b9e\n",
    "\n",
    "# Apply Lisa's changes\n",
    "git branch logger\n",
    "git switch logger\n",
    "git apply /workspaces/practice-git/notebooks/use-logger.patch"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d470be4e",
   "metadata": {},
   "source": [
    "**Tasks**:\n",
    "\n",
    "- Analyze the changes using the Git GUI\n",
    "- Commit the changes using an informative commit message"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d0ce2410",
   "metadata": {},
   "outputs": [],
   "source": [
    "# We go back to the main branch and apply another patch\n",
    "git switch main\n",
    "# Apply Ted's changes\n",
    "git apply /workspaces/practice-git/notebooks/replace-color-import.patch"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f5208e02",
   "metadata": {},
   "source": [
    "**Tasks**:\n",
    "\n",
    "<div style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify;\">\n",
    " \n",
    "<ul>\n",
    "<li>Analyze the changes using the Git GUI</li>\n",
    "<li>Commit the changes</li>\n",
    "<li>Merge the logger branch and resolve the conflict, making sure that the changes of Lisa and Ted are retained correctly</li>\n",
    "</ul>\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d5dc2c9d",
   "metadata": {},
   "outputs": [],
   "source": [
    "git merge logger\n",
    "# Resolve merge conflict\n",
    "git status\n",
    "# Once resolved, create a merge commit as advised in the git status"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "314aaa7d",
   "metadata": {},
   "source": [
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\">To validate your solution, run the following command to retrieve our solution:</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1a7b722f",
   "metadata": {},
   "outputs": [],
   "source": [
    "cp -f /workspaces/practice-git/cli.py colrev/ui_cli/cli.py\n",
    "git status"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "009ab660",
   "metadata": {},
   "source": [
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\">Note: for simplicity, we worked in the same repository. But the merge conflict would be identical if the branches were shared in a remote repository. In fact, if GitHub encounters a merge conflict, it suggests that users download the branches and resolve the merge conflict locally (like we just did).</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f9fc4343",
   "metadata": {},
   "source": [
    "## Part 3: Understand how to prevent merge conflicts <a id=\"prevent\"></a>\n",
    "\n",
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\">Although merge conflicts are not necessarily a bad thing, it is recommended to avoid complex merge conflicts. To achieve this, different strategies can be combined:</p>\n",
    "\n",
    "<div style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify;\">\n",
    " \n",
    "<ul>\n",
    "<li>Understand whether changes are likely to create merge conflicts</li>\n",
    "<li>Communicate with other contributors to understand who is working on which parts of the codebase or read the codebase if there is no personal contact with the other developers</li>\n",
    "<li>Avoid problematic changes, such as code formatting and restructuring that affects the whole codebase. Coordinate development if they are neccessary.</li>\n",
    "<li>Avoid long-running branches by merging often</li>\n",
    "<li>Create atomic commits</li>\n",
    "</ul>\n",
    "\n",
    "</div>\n",
    "\n",
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\">When learning Git, this is surprising for many: A branch gives you a completely independent version of the codebase, allowing you to test changes and \"do your thing\". But to use branches in the most effective way possible, you have to anticipate how your changes will integrate with the work of others.</p>\n",
    "\n",
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\"><b>Task</b>: To understand whether commits are likely to create merge conflicts, examine the following commits:</p>\n",
    "\n",
    "<a href=\"https://github.com/CoLRev-Environment/colrev/commit/108d278e\" target=\"_blank\">Commit 1</a>\n",
    "\n",
    "<details><summary {style='color:green;font-weight:bold'}>Check</summary>\n",
    "\n",
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\"><b>Solution</b>: Over 500 files changed. But mostly in the <code>docs</code> directory and mostly whitespace changes. It would be better to maintain consistent formatting from the start, but this commit is <b>not very likely to create merge conflicts</b>.</p>\n",
    "\n",
    "</details>\n",
    "\n",
    "<a href=\"https://github.com/CoLRev-Environment/colrev/commit/8b14c4ef\" target=\"_blank\">Commit 2</a>\n",
    "\n",
    "<details><summary {style='color:green;font-weight:bold'}>Check</summary>\n",
    "\n",
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\"><b>Solution</b>: Many changes throughout the codebase. This <b>may raise merge conflicts</b> when attempting to integrate changes from another branch.</p>\n",
    "\n",
    "</details>\n",
    "\n",
    "<a href=\"https://github.com/CoLRev-Environment/colrev/commit/1d18548d\" target=\"_blank\">Commit 3</a>\n",
    "\n",
    "<details><summary {style='color:green;font-weight:bold'}>Check</summary>\n",
    "\n",
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\"><b>Solution</b>: Many files changed, but mostly \"dead code\". This is <b>unlikely to raise merge conflicts</b>.</p>\n",
    "\n",
    "</details>\n",
    "\n",
    "<a href=\"https://github.com/CoLRev-Environment/colrev/commit/689b7603\" target=\"_blank\">Commit 4</a>\n",
    "\n",
    "<details><summary {style='color:green;font-weight:bold'}>Check</summary>\n",
    "\n",
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\"><b>Solution</b>: Many changes (+- 6,000 lines) in many central parts of the codebase. This has a <b>very high probability of creating merge conflicts</b>. Before introducing such fundamental changes, it makes sense to complete and merge all parallel development in branches. A maintainer who adds such a substantial change without notifying other contributors would be reckless. If a contributor suggested to merge such a change, it would probably be rejected.</p>\n",
    "\n",
    "</details>\n",
    "\n",
    "<a href=\"https://github.com/CoLRev-Environment/colrev/commit/5142f4db641252e2bd667752cf3a9d7ae54e7cfa\" target=\"_blank\">Commit 5</a>\n",
    "\n",
    "<details><summary {style='color:green;font-weight:bold'}>Check</summary>\n",
    "\n",
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\"><b>Solution</b>: Single line change in a config file. <b>Very unlikely to create a merge conflict</b></p>\n",
    "\n",
    "</details>\n",
    "\n",
    "<a href=\"https://github.com/CoLRev-Environment/colrev/commit/b52f52e94c2685920bd46effbac8b75dca7a04a2\" target=\"_blank\">Commit 6</a>\n",
    "\n",
    "<details><summary {style='color:green;font-weight:bold'}>Check</summary>\n",
    "\n",
    "<p style=\"max-width: 800px; margin-left: 0; margin-right: 0; text-align: justify; width: 800px;\"><b>Solution</b>: Changes in a lock file that was generated by some algorithm. In this case, it could be problematic to resolve merge conflicts manually. It would be necessary to understand what generates the file and check whether it the process can be rerun when merging branches.</p>\n",
    "\n",
    "</details>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0ef7d8e8",
   "metadata": {},
   "source": [
    "<div style=\"border: 2px solid #ff9800; padding: 10px; background-color: #ffe0b2; color: #e65100; border-radius: 5px; width: 800px; margin: 20px;\">\n",
    "    <strong>Warning: Misleading Assumption!</strong> <br/>\n",
    "    <p>Working on a separate Git branch can create the illusion that you can radically reorganize the codebase without any consequences. While it's true that changes made in a branch are isolated, remember that these changes will eventually be merged into the main codebase. If you drastically reorganize files or the structure, it could create significant merge conflicts, and disrupt team workflows.</p>\n",
    "    <p><strong>Catch yourself if you're thinking:</strong> \"I'm on my own branch, so I'll just reorganize the codebase before creating my feature.\"</p>\n",
    "    <p>Always consider how your changes will affect the project once merged, and coordinate with your team before undertaking major refactoring.</p>\n",
    "</div>\n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "247caf88",
   "metadata": {},
   "source": [
    "## Wrap-up <a id=\"wrap-up\"></a>\n",
    "\n",
    "🎉🎈 You have completed the Git merging notebook - good work! 🎈🎉\n",
    "\n",
    "In this notebook, we have learned to\n",
    "\n",
    "- Prevent merge conflicts from happening\n",
    "- Resolve merge conflicts once they occur\n",
    "\n",
    "Remember to delete your codespace [here](https://github.com/codespaces) (see [instructions](codespaces.ipynb))."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.20"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}