[PATCH v2] Documentation: mention the amlog in howto/maintain-git.txt

From: Taylor Blau <me@ttaylorr.com>
Date: Oct 2, 2024, 15:03 UTC
Message-ID: <5cc8e2bcb88424d8dce526f518282e4b26a1760a.1727881364.git.me@ttaylorr.com>
In-Reply-To: <a4b1da93e16d88323181f8f8444f01d96e09ef45.1727729100.git.me@ttaylorr.com>

Part of the maintainer's job is to keep up-to-date and publish the 'amlog' which stores a mapping between a patch's 'Message-Id' e-mail header and the commit generated by applying said patch.

But our Documentation/howto/maintain-git.txt does not mention the amlog, or the scripts which exist to help the maintainer keep the amlog up-to-date.

(This bit me during the first integration round I did as interim maintainer[1] involved a lot of manual clean-up. More recently it has come up as part of a research effort to better understand a patch's lifecycle on the list[2].)

Address this gap by briefly documenting the existence and purpose of the 'post-applypatch' hook in maintaining the amlog entries.

[1]: https://lore.kernel.org/git/Y19dnb2M+yObnftj@nand.local/ [2]: https://lore.kernel.org/git/CAJoAoZ=4ARuH3aHGe5yC_Xcnou_c396q_ZienYPY7YnEzZcyEg@mail.gmail.com/

Suggested-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Taylor Blau <me@ttaylorr.com>
---
Similar to v1, but with:

- an added change to "The Policy" section written by Junio

- a tab/space fix in the notes.rewriteRef example

- and a mention of the fact that the notes.rewriteRef configuration is
  not read by 'cherry-pick'.

 Documentation/howto/maintain-git.txt | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt
index da31332f11..76d6688d4c 100644
--- a/Documentation/howto/maintain-git.txt
+++ b/Documentation/howto/maintain-git.txt
@@ -122,6 +122,13 @@ Note that before v1.9.0 release, the version numbers used to be
 structured slightly differently.  vX.Y.Z were feature releases while
 vX.Y.Z.W were maintenance releases for vX.Y.Z.

+Because most of the lines of code in Git are written by individual
+contributors, and contributions come in the form of e-mailed patches
+published on the mailing list, the project maintains a mapping from
+individual commits to the Message-Id of the e-mail that resulted in
+the commit, to help tracking the origin of the changes. The notes
+in "refs/notes/amlog" are used for this purpose, and are published
+along with the broken-out branches to the maintainer's repository.

 A Typical Git Day
 -----------------
@@ -165,6 +172,24 @@ by doing the following:
    In practice, almost no patch directly goes to 'master' or
    'maint'.

+   The maintainer is expected to update refs/notes/amlog with a
+   mapping between the applied commit and the 'Message-Id'
+   corresponding to the e-mail which carried the patch.
+
+   This mapping is created with the aid of the "post-applypatch" hook
+   found in the 'todo' branch. That hook should be installed before
+   applying patches. It is also helpful to carry forward any relevant
+   amlog entries when rebasing, so the following config may be useful:
+
+      [notes]
+        rewriteRef = refs/notes/amlog
+
+   (note that this configuration is not read by 'cherry-pick').
+
+   Finally, take care that the amlog entries are pushed out during
+   integration cycles since external tools and contributors (in
+   addition to internal scripts) may rely on them.
+
  - Review the last issue of "What's cooking" message, review the
    topics ready for merging (topic->master and topic->maint).  Use
    "Meta/cook -w" script (where Meta/ contains a checkout of the

Range-diff against v1:
1:  a4b1da93e1 ! 1:  5cc8e2bcb8 Documentation: mention the amlog in howto/maintain-git.txt
    @@ Commit message
         [2]: https://lore.kernel.org/git/CAJoAoZ=4ARuH3aHGe5yC_Xcnou_c396q_ZienYPY7YnEzZcyEg@mail.gmail.com/

         Suggested-by: Junio C Hamano <gitster@pobox.com>
    +    Helped-by: Junio C Hamano <gitster@pobox.com>
         Signed-off-by: Taylor Blau <me@ttaylorr.com>

      ## Documentation/howto/maintain-git.txt ##
    +@@ Documentation/howto/maintain-git.txt: Note that before v1.9.0 release, the version numbers used to be
    + structured slightly differently.  vX.Y.Z were feature releases while
    + vX.Y.Z.W were maintenance releases for vX.Y.Z.
    +
    ++Because most of the lines of code in Git are written by individual
    ++contributors, and contributions come in the form of e-mailed patches
    ++published on the mailing list, the project maintains a mapping from
    ++individual commits to the Message-Id of the e-mail that resulted in
    ++the commit, to help tracking the origin of the changes. The notes
    ++in "refs/notes/amlog" are used for this purpose, and are published
    ++along with the broken-out branches to the maintainer's repository.
    +
    + A Typical Git Day
    + -----------------
     @@ Documentation/howto/maintain-git.txt: by doing the following:
         In practice, almost no patch directly goes to 'master' or
         'maint'.
    @@ Documentation/howto/maintain-git.txt: by doing the following:
     +   amlog entries when rebasing, so the following config may be useful:
     +
     +      [notes]
    -+	rewriteref = refs/notes/amlog
    ++        rewriteRef = refs/notes/amlog
    ++
    ++   (note that this configuration is not read by 'cherry-pick').
     +
     +   Finally, take care that the amlog entries are pushed out during
     +   integration cycles since external tools and contributors (in

base-commit: 3857aae53f3633b7de63ad640737c657387ae0c6
--
2.47.0.rc0.4.gd73fb26592.dirty