From 2bf8b7073c7e56e2d4d0f01c906567bc1f1f6bfc Mon Sep 17 00:00:00 2001
From: Tal Einat <taleinat@gmail.com>
Date: Sun, 17 Nov 2019 20:43:03 +0200
Subject: [PATCH 1/2] improve instructions about merging in the step-by-step
 guide

---
 pullrequest.rst | 50 +++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 44 insertions(+), 6 deletions(-)

diff --git a/pullrequest.rst b/pullrequest.rst
index 0cd00253a..1b71a491e 100644
--- a/pullrequest.rst
+++ b/pullrequest.rst
@@ -94,12 +94,6 @@ You should have already :ref:`set up your system <setup>`,
 
      git push origin <branch-name>
 
-* If someone else added new changesets and you get an error::
-
-     git fetch upstream
-     git merge upstream/master
-     git push origin <branch-name>
-
 * Finally go on :samp:`https://github.com/{<your-username>}/cpython`: you will
   see a box with the branch you just pushed and a green button that allows
   you to create a pull request against the official CPython repository.
@@ -114,6 +108,21 @@ You should have already :ref:`set up your system <setup>`,
    git commit -m '<message>'
    git push origin <branch-name>
 
+  * If someone else added new changesets and you get an error::
+
+     git checkout <branch-name>
+     git pull origin <branch-name>  # pull = fetch + merge
+     # if there are merge conflicts: see "Resolving Merge Conflicts" below
+     git push origin <branch-name>
+
+* If time passes and there are merge conflicts with the master branch, merge
+  the changes from the master branch while resolving the conflicts locally::
+
+   git checkout <branch-name>
+   git pull upstream master  # pull = fetch + merge
+   # resolve conflicts: see "Resolving Merge Conflicts" below
+   git push origin <branch-name>
+
 * After your PR has been accepted and merged, you can :ref:`delete the branch
   <deleting_branches>`::
 
@@ -125,6 +134,35 @@ You should have already :ref:`set up your system <setup>`,
    workflow is **strongly** preferred.
 
 
+.. _resolving-merge-conflicts:
+
+Resolving Merge Conflicts
+'''''''''''''''''''''''''
+
+When merging changes from different branches (or variants of a branch on
+different repos), the two branches may contain incompatible changes to one
+or more files. These are called "merge conflicts" and need to be manually
+resolved as follows:
+
+#. Check which files have merge conflicts::
+
+      git status
+
+#. Edit the affected files and bring them to their intended final state.
+   Make sure to remove the special "conflict markers" inserted by git.
+
+#. Commit the affected files::
+
+      git add <filenames>
+      git merge --continue
+
+When running the final command, git may open an editor for writing a commit
+message. It is usually okay to leave that as-is and close the editor.
+
+See `the merge command's documentation <https://git-scm.com/docs/git-merge>`_
+for a detailed technical explanation.
+
+
 .. _good-prs:
 
 Making Good PRs

From 4bc4367c1986144bb3ceee76efdafb4b1a4821c3 Mon Sep 17 00:00:00 2001
From: Tal Einat <taleinat@gmail.com>
Date: Mon, 18 Nov 2019 08:53:06 +0200
Subject: [PATCH 2/2] address code review comments

---
 pullrequest.rst | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/pullrequest.rst b/pullrequest.rst
index 1b71a491e..859261948 100644
--- a/pullrequest.rst
+++ b/pullrequest.rst
@@ -108,14 +108,17 @@ You should have already :ref:`set up your system <setup>`,
    git commit -m '<message>'
    git push origin <branch-name>
 
-  * If someone else added new changesets and you get an error::
+  * If a core developer reviewing your PR pushed one or more commits to your
+    PR branch, then after checking out your branch and before editing, run::
 
-     git checkout <branch-name>
      git pull origin <branch-name>  # pull = fetch + merge
-     # if there are merge conflicts: see "Resolving Merge Conflicts" below
-     git push origin <branch-name>
 
-* If time passes and there are merge conflicts with the master branch, merge
+    If you have made local changes that have not been pushed to your fork and
+    there are merge conflicts, git will warn you about this and enter conflict
+    resolution mode. See :ref:`resolving-merge-conflicts` below.
+
+* If time passes and there are merge conflicts with the master branch, GitHub
+  will show a warning to this end and you may be asked to address this. Merge
   the changes from the master branch while resolving the conflicts locally::
 
    git checkout <branch-name>