Merge pull request github#578 from github/merge-conflict

Managing Merge Conflicts course

.gitignore

@@ -9,3 +9,4 @@ _site/
 _release
 *.map
 .jekyll-metadata
+# *.resume-burger-jokes

_data/navigation.yml

@@ -274,3 +274,32 @@ electron-share-your-app:
     url: /electron/share-your-app/share-on-websites/
   - title: "Celebrate"
     url: /electron/share-your-app/celebrate/
+
+merge-conflicts:
+  - title: "Managing Merge Conflicts"
+    url: /merge-conflicts/
+  - title: "Set Up the Repository"
+    url: /merge-conflicts/setup/
+  - title: "A Normal Merge"
+    url: /merge-conflicts/normal-merge/
+  - title: "Merge Conflict Description"
+    url: /merge-conflicts/mc-description/
+  - title: "Your First Conflict"
+    url: /merge-conflicts/first-conflict/
+  - title: "Bob's Simple Conflict"
+    url: /merge-conflicts/example-01/
+  - title: "Teddy, Mort, and Jimmy Help"
+    url: /merge-conflicts/example-02/
+  - title: "Gene and Louise Lend a Hand"
+    url: /merge-conflicts/example-03/
+  - title: "What Next?"
+    url: /merge-conflicts/what-next/
+  - title: "Using GUIs to Handle Merge Conflicts"
+    url: /merge-conflicts/ide-intro/
+    children:
+    - title: "Atom"
+      url: /merge-conflicts/ide-atom/
+    - title: "Visual Studio Code"
+      url: /merge-conflicts/ide-vs-code/
+    - title: "GitHub Extension for Visual Studio"
+      url: /merge-conflicts/ide-vs-ext/

_includes/tell-me-why/merge-conflict.md

@@ -0,0 +1,14 @@
+[//]: # "This is used in both the CLI and Desktop course"
+
+## Examing Merge Conflicts
+
+Looking at an example merge conflict from our [help](https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/) documentation, we can discuss the different pieces that encompass a merge conflict.
+
+    If you have questions, please
+    <<<<<<< HEAD
+    open an issue
+    =======
+    ask your question in IRC.
+    >>>>>>> branch-a
+
+The <, =, and > symbols simply identify where the merge conflict occurred. We can see that both HEAD and branch-a are listed in the merge conflict. HEAD is pointing to the branch that you are currently checked out to, so it might say the branch you currently are on or HEAD. The other branch listed, in this example, branch-a identifies that changes exist on another branch that conflict with the changes we made.

index.html

@@ -23,6 +23,11 @@
     image: images/about/collabocats.jpg
     imageAlt: The 'collabocats', cartoon of octocats pictured on two laptops with symbols showing they're collaborating on code
     link: /github-cli
+  - title: Managing Merge Conflicts
+    description: First you had issues, now you have conflicts. Learn how to resolve at least one of them.
+    image: ./images/skatetocat.png
+    imageAlt: The 'skatetocat', a cartoon of an octocat using a skateboard and having fun
+    link: /merge-conflicts    
   - title: GitHub for Windows Users
     description: Learn how to configure your local git environment to work with GitHub and how to complete GitHub flow using the GitHub Extension for Visual Studio.
     image: images/red-polo.png

paths/merge-conflict/00-intro.md

@@ -0,0 +1,25 @@
+---
+layout: simple-class
+header:
+  overlay_image: cover.jpeg
+  overlay_filter: rgba(46, 129, 200, 0.6)
+title: Managing Merge Conflicts
+permalink: /merge-conflicts/
+next-page: /merge-conflicts/setup/
+sidebar:
+  nav: "merge-conflicts"
+main-content: |
+  You might have heard the term _merge conflict_ in hushed whispers from another Git user. Maybe you've encountered one yourself and had to Google your way out. You might also just be exploring everything Git has to offer and have no idea what a merge conflict is.
+
+  This course is designed for all of you. We demystify the merge conflict and, through a series of examples, prepare you to face off against the evil merge conflict and be the hero of the day!
+
+  ![louise saying yes yes yes yes yes](https://media.giphy.com/media/xdeQFr16i4y64/giphy.gif)
+
+  In this course, we've created a few conflicts for you to resolve in a sample repository. This repository contains a [GitHub Pages](https://pages.github.com/) powered [resume](https://github.com/jglovier/resume-template). That means, when you finish this course, you'll have more than a few merge conflicts under your belt. You'll also have a shiny new resume.
+
+  Don't worry. When you're all done, we'll provide instructions for polishing your resume and getting it ready to share with others.
+
+  It's a good idea to complete a few other courses first, specifically the [Introduction to GitHub](../intro-to-github/), and either [GitHub Pages from GitHub Desktop](../github-desktop/) or [GitHub Pages from the Command Line](../github-cli/).
+
+  If you have any questions while taking the course, make sure to create an Issue in the primary [class repository](https://github.com/githubschool/on-demand-merge-conflict/issues).
+---

paths/merge-conflict/01-normal-merge.md

@@ -0,0 +1,32 @@
+---
+layout: simple-class
+header:
+  overlay_image: cover.jpeg
+  overlay_filter: rgba(46, 129, 200, 0.6)
+title: A Normal Merge
+permalink: /merge-conflicts/normal-merge/
+next-page: /merge-conflicts/first-conflict/
+sidebar:
+  nav: "merge-conflicts"
+main-content: |
+  Before we delve into the world of merge conflicts, we should discuss what a merge is normally doing. Let's say you take some commits from `new-feature` branch and merge them into `master`. Simply, you're applying the commits that you made on the `new-feature` branch to the `master` branch.
+
+  It's common to merge a lot of branches with no problems before you encounter your first merge conflict. That's because Git is really smart when it comes merging. However, sometimes you and another collaborator both have an idea for a change to the same code, and Git needs you to examine the conflicting changes before it can successfully implement the changes.
+
+  Let's see a normal merge, and how it differs from a merge conflict.
+
+  1. In your repository, create a new branch named `my-title`
+  1. In `_config.yml`, change lines 2-3 to give your resume a title, and a description.
+  1. Commit your changes.
+  1. Open a Pull Request. Set the **base:** drop-down to `master` and the **compare:** drop-down of `my-title`
+  1. :warning: Do not merge yet! :warning: This pull request can be merged and contains no conflicts. This is because no conflicting commits appear on `master`, the target of our merge. We will introduce a conflict and merge in the following page.
+
+tell-me-why: |
+
+  There are two types of merge strategies that we're interested in: fast forward and recursive
+
+  In a *fast forward merge*, no commits have occurred in our target branch since we branched. Therefore, the easiest way to combine the changes from both branches is to fast-forward the HEAD pointer to your most recent commit on the topic branch. Because the history of both branches is one and the same, there's no competition and, therefore, no possibility for merge conflicts in a fast forward merge.
+
+  In a *recursive merge*, commits have occurred in both branches since we branched. Not all recursive merges result in conflicts, but when the new commits (since merging) on both branches attempt to edit the same line of the same file, a merge conflict will appear.
+
+---

paths/merge-conflict/02-mc-desc.md

@@ -0,0 +1,39 @@
+---
+layout: simple-class
+header:
+  overlay_image: cover.jpeg
+  overlay_filter: rgba(46, 129, 200, 0.6)
+title: Merge Conflict Description
+permalink: /merge-conflicts/mc-description/
+next-page: /merge-conflicts/example-01/
+sidebar:
+  nav: "merge-conflicts"
+main-content: |
+  To explain a merge conflict, it might be useful to have an example. Imagine we are creating a template for people to describe themselves. You might have something that looks like this:
+
+  ```
+  Name: First Last
+  Location: I Live Here
+  Favorite Animal: Octocat
+  ```
+
+  Now, let's imagine that Linda and Louise Belcher decide to change the default `Favorite Animal` in the template. So they might have something that looks like this:
+
+  **Louise**
+  ```
+  Favorite Animal: Kuchi Kopi
+  ```
+
+  **Linda**
+  ```
+  Favorite Animal: Akkorokamui
+  ```
+
+  When **Louise** merges her changes into the deployment branch, she won't encounter a merge conflict.
+
+  ![louise laughing over fire](https://media.giphy.com/media/dfIQG68floQuY/giphy.gif)
+
+  However, when **Linda** tries to merge her changes into the deployment branch, she is going to encounter a merge conflict.
+
+  ![linda screaming](https://media.giphy.com/media/l0IyoieFSfr2Xcbza/giphy.gif)
+---

paths/merge-conflict/02-setup-repository.md

@@ -0,0 +1,24 @@
+---
+layout: simple-class
+header:
+  overlay_image: cover.jpeg
+  overlay_filter: rgba(46, 129, 200, 0.6)
+title: Set Up the Repository
+permalink: /merge-conflicts/setup/
+next-page: /merge-conflicts/normal-merge/
+sidebar:
+  nav: "merge-conflicts"
+main-content: |
+  To participate in this course, you're going to need to **import** a project from the [GitHub School organization](https://github.com/githubschool). Importing a project will essentially copy the repository -- including all of the files, branches and history to your account.
+
+  [![instructions for using the repository import tool](../../images/gifs/merge-conflict/import-repo.gif)](../../images/gifs/merge-conflict/import-repo.gif)
+
+  1. While logged into GitHub, navigate to the [Import tool](https://github.com/new/import).
+  1. In the **Your old repository's clone URL** field, enter:
+
+         https://github.com/githubschool/on-demand-merge-conflict.git
+  1. Ensure that the **Owner** field is your account.
+  1. In the **Name** field, enter a new name for your repository. Since this course not only teaches you about merge conflicts but also provides a GitHub Pages powered resume template, maybe something like `resume` would work.
+  1. Select **Public** under the privacy options.
+  1. Click **Begin import**.
+---

paths/merge-conflict/02-your-first-conflict.md

@@ -0,0 +1,22 @@
+---
+layout: simple-class
+header:
+  overlay_image: cover.jpeg
+  overlay_filter: rgba(46, 129, 200, 0.6)
+title: Your First Conflict
+permalink: /merge-conflicts/first-conflict/
+next-page: /merge-conflicts/mc-description/
+sidebar:
+  nav: "merge-conflicts"
+main-content: |
+  You're here to learn about conflicts! So let's get conflicted.
+
+  1. Check out to the `master` branch.
+  1. In `_config.yml`, change lines 2-3 again to update your resume's title, and description. Ensure your changes are different from those in step 2 from the previous page of instructions.
+  1. Return to your Pull Request. A conflict now appears because `my-title` is based on a previous point in history, and new commits override our proposed change. Let's solve this, our first conflict. Click on **Resolve conflict**.
+  1. Remove the conflict markers and choose your desired title.
+  1. Click **Mark as resolved**.
+  1. Your Pull Request is now free of conflicts. Press the big green button to merge your pull request!
+
+tell-me-why:
+---

paths/merge-conflict/04-ex-01.md

@@ -0,0 +1,41 @@
+---
+layout: simple-class
+header:
+  overlay_image: cover.jpeg
+  overlay_filter: rgba(46, 129, 200, 0.6)
+title: Bob's Simple Conflict
+permalink: /merge-conflicts/example-01/
+next-page: /merge-conflicts/example-02/
+sidebar:
+  nav: "merge-conflicts"
+main-content: |
+  We need to modify the resume template so it contains our information. Using the GitHub Flow, we can make those changes by:
+
+  [![instructions for this activity](../../images/gifs/merge-conflict/config-merge.gif)](../../images/gifs/merge-conflict/config-merge.gif)
+
+  1. In your imported version of the repository, checkout to the branch named: `username-config`.
+  1. While on that branch, open the `_config.yml` file.
+  1. Lines 12-19 should be modified with your information. If you would prefer to create a fictional resume, your favorite fictional character's information.
+  1. After making the changes, create a commit, an example commit message might be: `Add my information`.
+
+      > If you made the changes on your local machine, push your changes back to repository on GitHub.
+
+  1. Create a new pull request. Use the **base:** of `master` and the **compare:** of `username-config`.
+  1. Although GitHub reports that you can't automatically merge these changes, you can still start the pull request. Click **Create pull request**.
+  1. In the **This branch has conflicts that must be resolved** section of the pull request, click the **Resolve conflicts** button to resolve the merge conflict.
+  1. It would appear that Bob Belcher recently made changes to the `master` branch and modified the exact same line you did, this is what caused the merge conflict to occur. Click "Resolve conflicts", and remove Bob's contributions to the `gh-pages` branch by deleting all of the content below the `=======` and above the `>>>>>>> gh-pages` content.
+
+      > To dive into all of the odd symbols on your screen, check out the **Tell me why** section.
+
+      ![bob saying we are radically off plan](https://media.giphy.com/media/ZUShN4lbUvAt2/giphy.gif)
+
+  1. We still can't mark as resolved because we need to remove the merge conflict markers. Delete the following lines: `<<<<<<< username-config`, `=======`, and `>>>>>>> gh-pages`.
+  1. With the merge conflict markers removed, click **Mark as resolved**. Congratulations, you successfully resolved a merge conflict! Go ahead and merge the pull request.
+
+      ![bob belcher excited about your progress](https://media.giphy.com/media/26ufhng4a2DRC5huw/giphy.gif)
+
+tell-me-why:
+  includes:
+    - /tell-me-why/merge-conflict.md
+
+---

paths/merge-conflict/05-ex-02.md

@@ -0,0 +1,40 @@
+---
+layout: simple-class
+header:
+  overlay_image: cover.jpeg
+  overlay_filter: rgba(46, 129, 200, 0.6)
+title: Teddy, Mort, and Jimmy Help
+permalink: /merge-conflicts/example-02/
+next-page: /merge-conflicts/example-03/
+sidebar:
+  nav: "merge-conflicts"
+main-content: |
+
+  Since we customized the resume to include our information, we should include our current professional experience. To include our experience we need to modify the `experience.yml` file.
+
+  [![instructions for this activity](../../images/gifs/merge-conflict/exp-merge.gif)](../../images/gifs/merge-conflict/exp-merge.gif)
+
+  1. In your imported version of the repository, checkout to the branch named: `username-experience`.
+  1. While on that branch, open the `_data/experience.yml` file.
+  1. Modify on the content on lines 2 through 6 making sure to provide information in the `company`, `position`, `duration`, and `summary` lines.
+  1. Save your changes to the `experience.yml` file and create a new commit.
+
+        > If you made the changes on your local machine, push your changes back to repository on GitHub.
+
+  1. Create a new pull request. Use the **base:** of `master` and the **compare:** of `username-experience`.
+  1. Click **Create pull request**.
+  1. In the **This branch has conflicts that must be resolved** section of the pull request, click the **Resolve conflicts** button to resolve the merge conflict.
+  1. It would appear that Teddy, Mort, and Jimmy Pesto recently made changes to the `master` branch and modified the same file you did, this is what is causing the merge conflicts. Similar to when we had to resolve a merge conflict with Bob's changes, remove Teddy, Mort, and Jimmy's contributions from the `experience.yml` file. If you need a refresher on how to resolve a merge conflict, check the **I need a refresher** section below.
+
+       > In the video instructions above, you might notice that @beardofedu ran into 2 conflicts in the same file. That is because they edited lines 2 - 6 and 15 - 19, so Git identified the two changes within the file as two separate conflicts. Had they edited lines 2 - 19, it would have been one merge conflict.
+
+       ![teddy holding his eyes](https://media.giphy.com/media/3oKIP8IA2LPwJGFC4U/giphy.gif)
+
+  1. With the merge conflict markers removed, click **Mark as resolved** and merge your pull request.
+
+        ![teddy dancing](https://media.giphy.com/media/xT8qB6JscNB2d4HX3i/giphy.gif)
+
+refresh: |
+
+  To remove the merge conflict, we should identify the content we want to keep and the content we want to remove. Then, remove the unnecessary content, and remove all conflict markers.
+---

paths/merge-conflict/06-ex-03.md

@@ -0,0 +1,40 @@
+---
+layout: simple-class
+header:
+  overlay_image: cover.jpeg
+  overlay_filter: rgba(46, 129, 200, 0.6)
+title: Gene and Louise Lend a Hand
+permalink: /merge-conflicts/example-03/
+next-page: /merge-conflicts/ide-intro/
+sidebar:
+  nav: "merge-conflicts"
+main-content: |
+  So, our resume is slowly taking shape, after modifying the contact information in the `_config.yml` file, we turned our attention to the `experience.yml` file. To wrap up, we need to finish adding our education and interests to the resume.
+
+  [![instructions for this activity](../../images/gifs/merge-conflict/int-merge.gif)](../../images/gifs/merge-conflict/int-merge.gif)
+
+  1. In your imported version of the repository, checkout to the branch named: `username-education`.
+  1. While on that branch, open the `_data/education.yml` file.
+  1. Modify the content in the `degree`, `uni`, `year`, and `summary` lines.
+
+      > The `education.yml` file supports displaying awards you may have received, you can add that on a new line between `year:` and `summary:`.
+
+  1. Save your changes to the `education.yml` file and create a new commit.
+  1. While on the `username-education` branch, open the `_data/interests.yml` file.
+  1. Replace the existing interests with your interests. For example `description: Learning about Git and GitHub` could be one of your interests.
+  1. Save your changes to the `interests.yml` file and create a new commit.
+
+        > If you made the changes on your local machine, push your changes back to repository on GitHub.
+
+  1. Create a new pull request. Use the **base:** of `master` and the **compare:** of `username-education`.
+  1. Click **Create pull request**.
+  1. In the **This branch has conflicts that must be resolved** section of the pull request, you can click the **Resolve conflicts** button to resolve the merge conflict.
+  1. It would appear that Gene and Louise Belcher recently made changes to the `master` branch and modified the same files you did, this is what is causing the merge conflicts. Similar to when we had to resolve a merge conflict with Bob's changes, remove Gene's contributions from the `education.yml` and Louise's contributions from the `interests.yml` files.
+
+        ![gene and louise saying its a crisis](https://media.giphy.com/media/l0HFjUCsgWTmmUMDK/giphy.gif)
+
+  1. With the merge conflict markers removed, click **Mark as resolved** and merge your pull request.
+
+        ![gene trying to rip shirt](https://media.giphy.com/media/GVYVYgGCl8fVC/giphy.gif)
+
+---

paths/merge-conflict/07-ide-intro.md

@@ -0,0 +1,15 @@
+---
+layout: simple-class
+header:
+  overlay_image: cover.jpeg
+  overlay_filter: rgba(46, 129, 200, 0.6)
+title: Using GUIs to Handle Merge Conflicts
+permalink: /merge-conflicts/ide-intro/
+next-page: /merge-conflicts/ide-atom/
+sidebar:
+  nav: "merge-conflicts"
+main-content: |
+  Although we were able to resolve the merge conflicts we encountered in this course within the GitHub user interface, sometimes we need to resolve merge conflicts locally. This section is going to outline how merge conflicts can be resolved in text editors like [Atom](https://atom.io/) or [Visual Studio Code](https://code.visualstudio.com/) and Integrated Development Environments (IDEs) like [Visual Studio](https://www.visualstudio.com/) and [Eclipse](https://www.eclipse.org/ide/).
+
+  Have a favorite tool and want to add a guide on how to handle merge conflicts in it? Contribute to the [GitHub Training Kit](https://github.com/github/training-kit) repository.
+---