[PATCH v2] Documentation: mention the amlog in howto/maintain-git.txt
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
Emily Shaffer
