Revise the "Backporting merged changes" guide (GH-1819)

Author: StanFromIreland

core-team/committing.rst

@@ -149,44 +149,10 @@ bug fixes or security fixes. In almost all cases the fixes should first
 originate on ``main`` and then be ported back to older branches.
 
 
-.. _branch-merge:
-
 Backporting changes to an older version
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If it is determined that a pull request needs to be backported into one or
-more of the maintenance branches, then a core team member can apply the label
-``needs backport to X.Y`` to the pull request.
-
-After the pull request has been merged, miss-islington (bot) will first try to
-do the backport automatically. If miss-islington is unable to do it,
-then the pull request author or the core team member who merged it should look into
-backporting it themselves, using the backport generated by cherry_picker.py_
-as a starting point.
-
-You can get the commit hash from the original pull request, or you can use
-``git log`` on the ``main`` branch. To display the 10 most recent commit
-hashes and their first line of the commit, use the following command::
-
-   git log -10 --oneline
-
-.. _backport-pr-title:
-
-You can prefix the backport pull request with the branch, and reference
-the pull request number from ``main``. Here is an example::
-
-   [3.9] gh-12345: Fix the Spam Module (GH-NNNN)
-
-Here "gh-12345" is the GitHub *issue* number, and "GH-NNNN" is the
-number of the original *pull request*.
-Note that cherry_picker.py_ adds the branch prefix automatically.
-
-Once the backport pull request has been created, remove the
-``needs backport to X.Y`` label from the original pull request. (Only
-members of the core team and :ref:`Python Triage Team <triage-team>`
-can apply labels to GitHub pull requests).
-
-.. _cherry_picker.py: https://github.com/python/cherry-picker
+This section has moved to :ref:`branch-merge`.
 
 
 Reverting a merged pull request

getting-started/git-boot-camp.rst

@@ -557,60 +557,83 @@ dismissing your previous review that requested changes.
 Note that pushing new changes after the auto-merge flow was enabled
 does **NOT** stop it.
 
+
+.. _branch-merge:
+
 Backporting merged changes
 --------------------------
 
-A pull request may need to be backported into one of the maintenance branches
-after it has been accepted and merged into ``main``.  It is usually indicated
-by the label ``needs backport to X.Y`` on the pull request itself.
+After a pull request has been merged into ``main``, it may need to be backported
+to one or more :ref:`maintenance <maintbranch>` or :ref:`security <secbranch>`
+branches. This is indicated by the :samp:`needs backport to {X.Y}` labels on
+the pull request.
 
-Use the utility script
-`cherry_picker.py <https://github.com/python/cherry-picker>`__
-to backport the commit.
+``miss-islington`` will automatically attempt to create backport PRs for the
+versions indicated by these labels. If ``miss-islington`` cannot create a
+backport PR due to conflicts, you can use the :pypi:`cherry-picker` tool to
+create the backport and resolve the conflicts manually.
 
-The commit hash for backporting is the squashed commit that was merged to
-the ``main`` branch.  On the merged pull request, scroll to the bottom of the
-page.  Find the event that says something like:
+You need the commit hash of the squashed commit that was merged into
+the ``main`` branch. ``miss-islington`` should post a comment when it is unable
+to create the backport automatically, including the full command and commit hash.
+If that comment is not posted, look for an event on the merged
+pull request similar to:
 
 .. code-block:: text
 
    <core_developer> merged commit <commit_sha1> into python:main <sometime> ago.
 
-By following the link to ``<commit_sha1>``, you will get the full commit hash.
+By following the link to ``<commit_sha1>``, you can get the full commit hash.
 
-Alternatively, the commit hash can also be obtained by the following Git
+Alternatively, the commit hash can also be obtained with the following Git
 commands::
 
    $ git fetch upstream
-   $ git rev-parse ":/gh-12345"
+   $ git rev-parse ":/gh-<PR number>"
+
+These commands print the hash of the commit whose message contains ``gh-<PR number>``.
 
-The above commands will print out the hash of the commit containing
-``"gh-12345"`` as part of the commit message.
+You can then use the commit hash and the :pypi:`cherry-picker` tool to create
+the backport. In the following command, ``<branch>`` is the target maintenance
+branch (for example, ``3.12``):
+
+.. code-block:: text
 
-When formatting the commit message for a backport commit: leave the original
-one as is and delete the number of the backport pull request.
+   $ cherry_picker <commit_sha1> <branch>
 
-✅ Example of good backport commit message:
+Then, follow the instructions provided. You will have to identify the files
+with conflicts, fix them, and build and run applicable tests if necessary.
+When you are finished, ``git add`` all modified files and run
+``cherry_picker --continue`` to push the backport.
+
+The tool usually generates the commit message automatically. If it does not, use
+the following format: Keep the original commit message unchanged, except for
+removing the backport pull request number (``(#XXXXX)``). At the end of the
+message, append a ``(cherry picked from commit <commit_sha1>)`` line.
+
+The format of a correct backport commit message is:
 
 .. code-block:: text
    :class: good
 
-    gh-12345: Improve the spam module (GH-777)
+    [<branch>] gh-XXXXX: <original commit title> (GH-XXXXX)
 
-    * Add method A to the spam module
-    * Update the documentation of the spam module
+    <original commit body>
 
-    (cherry picked from commit 62adc55)
+    (cherry picked from commit <commit_sha1>)
 
-❌ Example of bad backport commit message:
+An example of a bad backport commit message:
 
 .. code-block:: text
    :class: bad
 
-    gh-12345: Improve the spam module (GH-777) (#888)
+    gh-XXXXX: Custom title (GH-XXXXX) (#XXXXX)
+
+    * Custom message
+
+After the backport PR is opened, ``miss-islington`` will link it to the original
+PR and remove the corresponding backport label.
 
-    * Add method A to the spam module
-    * Update the documentation of the spam module
 
 Editing a pull request prior to merging
 ---------------------------------------