diff --git a/core-team/committing.rst b/core-team/committing.rst index 1209d6ae1..0a5380e0f 100644 --- a/core-team/committing.rst +++ b/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 ` -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 diff --git a/getting-started/git-boot-camp.rst b/getting-started/git-boot-camp.rst index 47f49f3d6..95f6a94ca 100644 --- a/getting-started/git-boot-camp.rst +++ b/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 ` or :ref:`security ` +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-``. -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, ```` 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 -✅ 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 )`` line. + +The format of a correct backport commit message is: .. 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: +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 ---------------------------------------