diff --git a/core-developers/committing.rst b/core-developers/committing.rst index 74c10bbf1..256fda9d1 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -191,7 +191,8 @@ Seeing active branches If you use ``git branch``, then you will see a :ref:`list of branches `. The only branch that receives new features is ``main``, the in-development branch. The other branches receive only -bug fixes or security fixes. +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: diff --git a/getting-started/git-boot-camp.rst b/getting-started/git-boot-camp.rst index e29dc1e05..e27c4b06a 100644 --- a/getting-started/git-boot-camp.rst +++ b/getting-started/git-boot-camp.rst @@ -461,37 +461,66 @@ Accepting and Merging a Pull Request ------------------------------------ Pull requests can be accepted and merged by a Python Core Developer. +You can read more about what to look for before accepting a change +:ref:`here `. -1. At the bottom of the pull request page, click the ``Squash and merge`` - button. +All pull requests have required checks that need to pass before a change +can be merged. After a change was accepted by at least one core +developer review, you can schedule an automatic merge of the change by +clicking the gray ``Enable auto-merge (squash)`` button. You will find +it at the bottom of the pull request page. The auto-merge will only +happen if all the required checks pass. -2. Replace the reference to GitHub pull request ``#NNNN`` with ``GH-NNNN``. - If the title is too long, the pull request number can be added to the - message body. +If all required checks are already finished on a PR you're reviewing, +in place of the gray ``Enable auto-merge`` button you will find a green +``Squash and merge`` button. -3. Adjust and clean up the commit message. +In either case, adjust and clean up the commit message. - Example of good commit message:: +Here's an example of a **good** commit message:: - gh-12345: Improve the spam module (GH-777) + gh-12345: Improve the spam module (GH-777) - * Add method A to the spam module - * Update the documentation of the spam module + * Add method A to the spam module + * Update the documentation of the spam module - Example of bad commit message:: +Here's an example of a **bad** commit message:: - gh-12345: Improve the spam module (#777) + gh-12345: Improve the spam module (#777) - * Improve the spam module - * merge from main - * adjust code based on review comment - * rebased + * Improve the spam module + * merge from main + * adjust code based on review comment + * rebased - .. note:: - `How to Write a Git Commit Message `_ - is a nice article describing how to write a good commit message. +The bad example contains bullet points that are a direct effect of the +PR life cycle, while being irrelevant to the final change. -4. Press the ``Confirm squash and merge`` button. +.. note:: + `How to Write a Git Commit Message `_ + is a nice article describing how to write a good commit message. + +Finally, press the ``Confirm squash and merge`` button. + +Cancelling an Automatic Merge +----------------------------- + +If you notice a problem with a pull request that was accepted and where +auto-merge was enabled, you can still cancel the workflow before GitHub +automatically merges the change. + +Press the gray "Disable auto-merge" button on the bottom of the +pull request page to disable automatic merging entirely. This is the +recommended approach. + +To pause automatic merging, apply the "DO-NOT-MERGE" label to the PR or +submit a review requesting changes. The latter will put an "awaiting +changes" label on the PR, which pauses the auto-merge similarly to +"DO-NOT-MERGE". After the author submits a fix, re-requests review, and +receives a new accepting review, auto-merge will complete. + +Note that pushing new changes after the auto-merge flow was enabled +does **NOT** stop it. Backporting Merged Changes --------------------------