diff --git a/getting-started/git-boot-camp.rst b/getting-started/git-boot-camp.rst index 47f49f3d6..ba7961d2e 100644 --- a/getting-started/git-boot-camp.rst +++ b/getting-started/git-boot-camp.rst @@ -557,60 +557,80 @@ dismissing your previous review that requested changes. Note that pushing new changes after the auto-merge flow was enabled does **NOT** stop it. + 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 maintenance branches. This is indicated by the +:samp:`needs backport to {X.Y}` labels on the pull request. -Use the utility script -`cherry_picker.py `__ -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 merged commit into python:main ago. -By following the link to ````, you will get the full commit hash. +By following the link to ````, 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-" + +These commands print the hash of the commit whose message contains ``gh-``. + +You can then use the commit hash and the :pypi:`cherry-picker` tool to create +the backport. In the following command, ```` is the target maintenance +branch (for example, ``3.12``): + +.. code-block:: text + + $ cherry_picker -The above commands will print out the hash of the commit containing -``"gh-12345"`` as part of the 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. -When formatting the commit message for a backport commit: leave the original -one as is and delete the number of the backport pull request. +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 )`` line. -✅ Example of good backport commit message: +Example of good backport commit message: .. code-block:: text :class: good - gh-12345: Improve the spam module (GH-777) + gh-XXXXX: (GH-XXXXX) - * Add method A to the spam module - * Update the documentation of the spam module + - (cherry picked from commit 62adc55) + (cherry picked from commit ) -❌ Example of bad backport commit message: +Example of 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 ---------------------------------------