-
-
Notifications
You must be signed in to change notification settings - Fork 997
Revise the "Backporting merged changes" guide #1819
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
StanFromIreland
wants to merge
1
commit into
python:main
Choose a base branch
from
StanFromIreland:backport
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+45
−25
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -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 <https://github.com/python/cherry-picker>`__ | ||||||
| to backport the commit. | ||||||
| ``miss-islington`` will automatically attempt to create backport PRs for the | ||||||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
| 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 | ||||||
| --------------------------------------- | ||||||
|
|
||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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.