@matheusbsbs / matheus-bagliano / commits / ddfb5bcfc6

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> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Taylor Blau committed Oct 2, 2024 at 21:09 UTC ddfb5bcfc69265d62358c0ab939e313b861e8470
1 file changed +44
Documentation/howto/maintain-git.txt
+44
@@ -122,6 +122,13 @@ Note that before v1.9.0 release, the version numbers used to be
122 structured slightly differently. vX.Y.Z were feature releases while
123 vX.Y.Z.W were maintenance releases for vX.Y.Z.
124
125 +Because most of the lines of code in Git are written by individual
126 +contributors, and contributions come in the form of e-mailed patches
127 +published on the mailing list, the project maintains a mapping from
128 +individual commits to the Message-Id of the e-mail that resulted in
129 +the commit, to help tracking the origin of the changes. The notes
130 +in "refs/notes/amlog" are used for this purpose, and are published
131 +along with the broken-out branches to the maintainer's repository.
132
133 A Typical Git Day
134 -----------------
@@ -165,6 +172,43 @@ by doing the following:
172 In practice, almost no patch directly goes to 'master' or
173 'maint'.
174
175 + Applying the e-mailed patches using "git am" automatically records
176 + the mappings from 'Message-Id' to the applied commit in the "amlog"
177 + notes. Periodically check that this is working with "git show -s
178 + --notes=amlog $commit".
179 +
180 + This mapping is maintained with the aid of the "post-applypatch"
181 + hook found in the 'todo' branch. That hook should be installed
182 + before applying patches. It is also helpful to carry forward any
183 + relevant amlog entries when rebasing, so the following config may
184 + be useful:
185 +
186 + [notes]
187 + rewriteRef = refs/notes/amlog
188 +
189 + Avoid "cherry-pick", as it does not propagate notes by design. Use
190 + either "git commit --amend" or "git rebase" to make corrections to
191 + an existing commit, even for a single-patch topic.
192 +
193 + Make sure that a push refspec for 'refs/notes/amlog' is in the
194 + remote configuration for publishing repositories. A few sample
195 + configurations look like the following:
196 +
197 + [remote "github"]
198 + url = https://github.com/gitster/git
199 + pushurl = github.com:gitster/git.git
200 + mirror
201 +
202 + [remote "github2"]
203 + url = https://github.com/git/git
204 + fetch = +refs/heads/*:refs/remotes/github2/*
205 + pushurl = github.com:git/git.git
206 + push = refs/heads/maint:refs/heads/maint
207 + push = refs/heads/master:refs/heads/master
208 + push = refs/heads/next:refs/heads/next
209 + push = +refs/heads/seen:refs/heads/seen
210 + push = +refs/notes/amlog
211 +
212 - Review the last issue of "What's cooking" message, review the
213 topics ready for merging (topic->master and topic->maint). Use
214 "Meta/cook -w" script (where Meta/ contains a checkout of the