Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 45 additions & 25 deletions getting-started/git-boot-camp.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we have a section anywhere about deciding when to backport? If so, it would be good to link it here.

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 <https://github.com/python/cherry-picker>`__
to backport the commit.
``miss-islington`` will automatically attempt to create backport PRs for the
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
``miss-islington`` will automatically attempt to create backport PRs for the
The Miss Islington bot 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>``.

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
$ cherry_picker <commit_sha1> <branch>
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 <commit_sha1>)`` 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: <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:
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
---------------------------------------
Expand Down
Loading