Split backporting policy from the practical guide

developer-workflow/development-cycle.rst

@@ -74,20 +74,22 @@ produced from a maintenance branch are called **bugfix** or **maintenance**
 releases; the terms are used interchangeably. These releases have a
 **micro version** number greater than zero.
 
-Changes backported to a maintenance branch fall into two groups.  *Low-risk*
-changes (bug fixes, test improvements, and documentation edits) may be
-backported without debate.  *Higher-risk* changes (new features, semantic
-changes, and performance improvements) can introduce regressions, so they are
-not backported as a matter of course.
-Also, a general rule for maintenance branches is that compatibility
-must not be broken at any point between sibling micro releases (3.12.1, 3.12.2,
-etc.).  For both rules, only rare exceptions are accepted, and each requires a
+For ordinary changes, merge to ``main`` first.  A change may then be
+backported to a maintenance branch if it is appropriate for that release.
+Security fixes follow the coordinated process described in the
+:ref:`security policy <security-policy>`.  *Low-risk* changes (bug fixes, test
+improvements, and documentation edits) may be backported without debate.
+*Higher-risk* changes (new features, semantic changes, and performance
+improvements) can introduce regressions, so they are not backported as a matter
+of course.  Compatibility must not be broken between sibling micro releases
+(3.12.1, 3.12.2, etc.).  Exceptions to these rules are rare and require a
 strong case agreed upon in discussion beforehand.
 
-Backporting changes reduces the risk of future conflicts.
-For documentation, it increases the visibility of improvements,
-since most readers access the `stable documentation <https://docs.python.org/3/>`__
+Backport pull requests use a ``[X.Y]`` prefix in their title to identify the
+target branch.  Backporting documentation changes also makes improvements more
+visible, since most readers access the `stable documentation <https://docs.python.org/3/>`__
 rather than the `development documentation <https://docs.python.org/dev/>`__.
+For the practical steps, see :ref:`backporting`.
 
 A new maintenance branch is normally created when the next feature release
 cycle reaches feature freeze, that is, at its first beta pre-release.

getting-started/backporting.rst

@@ -0,0 +1,89 @@
+.. _backporting:
+.. _branch-merge:
+
+Backporting merged changes
+==========================
+
+After a pull request has been merged into ``main``, it may need to be backported
+to one or more :ref:`maintenance <maintbranch>` or :ref:`security <secbranch>`
+branches. The project's backport policy is described in the
+:ref:`development cycle guide <maintbranch>`.
+
+The :samp:`needs backport to {X.Y}` labels on a pull request indicate which
+versions should receive a backport. ``miss-islington`` will automatically
+attempt to create backport pull requests for the versions indicated by these
+labels. If it cannot create a backport pull request because of conflicts, use
+the :pypi:`cherry-picker` tool to create the backport and resolve the conflicts
+manually.
+
+You need the commit hash of the squashed commit that was merged into ``main``.
+``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 can get the full commit hash.
+
+Alternatively, you can obtain the commit hash with these Git commands::
+
+   $ git fetch upstream
+   $ git rev-parse ":/gh-<PR number>"
+
+These commands print the hash of the commit whose message contains
+``gh-<PR number>``.
+
+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>
+
+Follow the instructions provided. You may need to identify files with
+conflicts, fix them, and build and run applicable tests. When you are finished,
+stage all modified files and run ``cherry_picker --continue`` to push the
+backport.
+
+The tool usually generates the commit message automatically. If it does not,
+keep the original commit message unchanged, except for removing the backport
+pull request number (``(#XXXXX)``), and append a
+``(cherry picked from commit <commit_sha1>)`` line.
+
+The format of a correct backport commit message is:
+
+.. code-block:: text
+   :class: good
+
+    [<branch>] gh-XXXXX: <original commit title> (GH-XXXXX)
+
+    <original commit body>
+
+    (cherry picked from commit <commit_sha1>)
+
+Here ``gh-XXXXX`` is the GitHub *issue* number, and ``(GH-XXXXX)`` is the
+original *pull request* number.
+
+An example of a bad backport commit message:
+
+.. code-block:: text
+   :class: bad
+
+    gh-XXXXX: Custom title (GH-XXXXX) (#XXXXX)
+
+    * Custom message
+
+When opening the backport pull request, its title must follow the same format
+as the commit title, beginning with the ``[<branch>]`` prefix and referencing
+the original pull request with a ``(GH-XXXXX)`` suffix. For example:
+
+.. code-block:: text
+   :class: good
+
+    [3.15] gh-12345: Fix the spam module (GH-24680)
+
+After the backport pull request is opened, ``miss-islington`` will link it to
+the original pull request and remove the corresponding backport label.

getting-started/git-boot-camp.rst

@@ -560,93 +560,7 @@ does **NOT** stop it.
 
 .. _branch-merge:
 
-Backporting merged changes
---------------------------
-
-After a pull request has been merged into ``main``, it may need to be backported
-to one or more :ref:`maintenance <maintbranch>` or :ref:`security <secbranch>`
-branches. This is indicated by the :samp:`needs backport to {X.Y}` labels on
-the pull request.
-
-``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.
-
-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 can get the full commit hash.
-
-Alternatively, the commit hash can also be obtained with the following Git
-commands::
-
-   $ git fetch upstream
-   $ 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>
-
-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 <commit_sha1>)`` line.
-
-The format of a correct backport commit message is:
-
-.. code-block:: text
-   :class: good
-
-    [<branch>] gh-XXXXX: <original commit title> (GH-XXXXX)
-
-    <original commit body>
-
-    (cherry picked from commit <commit_sha1>)
-
-Here ``gh-XXXXX`` is the GitHub *issue* number, and ``(GH-XXXXX)`` is the
-original *pull request* number.
-
-An example of a bad backport commit message:
-
-.. code-block:: text
-   :class: bad
-
-    gh-XXXXX: Custom title (GH-XXXXX) (#XXXXX)
-
-    * Custom message
-
-.. _backport-pr:
-
-When opening the backport PR, its title PR must follow the same format as the
-commit title, beginning with the ``[<branch>]`` prefix and referencing the
-original PR with a ``(GH-XXXXX)`` suffix. For example:
-
-.. code-block:: text
-   :class: good
-
-    [3.15] gh-12345: Fix the spam module (GH-24680)
-
-After the backport PR is opened, ``miss-islington`` will link it to the original
-PR and remove the corresponding backport label.
+For instructions on backporting a merged change, see :ref:`backporting`.
 
 
 Editing a pull request prior to merging

getting-started/index.rst

@@ -11,6 +11,7 @@ Getting started
    setup-building
    fixing-issues
    git-boot-camp
+   backporting
    pull-request-lifecycle
    getting-help
    ai-tools