Extended committing code docs to add detailed instructions for backports.

Thanks to Jacob Walls for the original idea and the review.

1 files changed, 66 insertions, 18 deletions

diff --git a/docs/internals/contributing/committing-code.txt b/docs/internals/contributing/committing-code.txt
index 413745e644..fbfd6cf779 100644
--- a/docs/internals/contributing/committing-code.txt
+++ b/docs/internals/contributing/committing-code.txt
@@ -155,17 +155,14 @@ submitted by a contributor via a pull request or landed directly by a merger:
 
   .. _Co-Authored-By: https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors
 
-* For commits to a branch, prefix the commit message with the branch name.
-  For example: "[1.4.x] Fixed #xxxxx -- Added support for mind reading."
-
 * Limit commits to the most granular change that makes sense. This means,
   use frequent small commits rather than infrequent large commits. For
   example, if implementing feature X requires a small change to library Y,
   first commit the change to library Y, then commit feature X in a separate
   commit. This goes a *long way* in helping everyone follow your changes.
 
-* Separate bug fixes from feature changes. Bugfixes may need to be backported
-  to the stable branch, according to :ref:`supported-versions-policy`.
+* Separate bug fixes from feature changes. Bugfixes may need to be
+  :ref:`backported <backports>`.
 
 * If your commit closes a ticket in the Django `ticket tracker`_, begin
   your commit message with the text "Fixed #xxxxx", where "xxxxx" is the
@@ -190,33 +187,84 @@ submitted by a contributor via a pull request or landed directly by a merger:
   is the number of the ticket your commit references. This will automatically
   post a comment to the appropriate ticket.
 
-* Write commit messages for backports using this pattern:
+.. _backports:
 
-  .. code-block:: none
+Backports
+=========
 
-    [<Django version>] Fixed <ticket> -- <description>
+Bug fix backports to stable branches are done exclusively by mergers, following
+the :ref:`supported-versions-policy`. A backport consists of cherry-picking a
+commit from ``main`` onto the target ``stable/A.B.x`` branch.
 
-    Backport of <revision> from <branch>.
+A backport commit must include two things beyond the original commit message:
 
-  For example:
+* A prefix ``[A.B.x]`` on the subject line, where ``A.B.x`` is the name of the
+  ``stable/A.B.x`` branch being targeted.
 
-  .. code-block:: none
+* A suffix ``Backport of <sha> from main.`` line in the commit body, pointing
+  to the original commit hash.
+
+For example:
+
+.. code-block:: none
 
     [1.3.x] Fixed #17028 -- Changed diveintopython.org -> diveintopython.net.
 
     Backport of 80c0cbf1c97047daed2c5b41b296bbc56fe1d7e3 from main.
 
-  There's a `script on the wiki
-  <https://code.djangoproject.com/wiki/MergerTips#AutomatingBackports>`_ to
-  automate this.
+If the backport also fixes a regression, add a line identifying the commit that
+introduced it:
 
-  If the commit fixes a regression, include this in the commit message:
-
-  .. code-block:: none
+.. code-block:: none
 
     Regression in 6ecccad711b52f9273b1acb07a57d3f806e93928.
 
-  (use the commit hash where the regression was introduced).
+There are three ways to do a backport, depending on your workflow:
+
+**Option 1: fully manual**
+
+Cherry-pick the commit onto the stable branch, then amend the commit message to
+add the required prefix and backport note:
+
+.. code-block:: shell
+
+    git cherry-pick <sha>
+    git commit --amend
+
+If the cherry-pick produces conflicts, resolve them, stage the changes, then
+run ``git cherry-pick --continue`` before amending. This option requires no
+setup but relies entirely on remembering to format the message correctly.
+
+**Option 2: using the helper script in the repo**
+
+The ``scripts/backport.sh`` Bash script automates the cherry-pick and rewrites
+the commit message with the correct prefix and backport note. Run it from the
+target stable branch:
+
+.. code-block:: shell
+
+    bash scripts/backport.sh <sha>
+
+This is straightforward for clean cherry-picks, but if conflicts are produced,
+you will need to resolve them manually and add the prefix and backport note to
+the commit message yourself.
+
+**Option 3: using the** ``prepare-commit-msg`` **git hook**
+
+The ``scripts/prepare_commit_msg.py`` Python script can be installed as a
+``prepare-commit-msg`` git hook. It automatically adds the ``[A.B.x]`` prefix
+to the subject line, appends ``Backport of <sha> from main.`` to the commit
+body, and ensures the subject line ends with a period, even when the
+cherry-pick produces conflicts. To install it, create an executable file
+``.git/hooks/prepare-commit-msg`` containing:
+
+.. code-block:: sh
+
+    #!/bin/sh
+    exec python scripts/prepare_commit_msg.py "$@"
+
+Once installed, a plain ``git cherry-pick <sha>`` on a stable branch is
+sufficient; the hook handles the message formatting in all cases.
 
 Reverting commits
 =================