On Mon, Sep 30, 2024, at 22:45, Taylor Blau wrote: > 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@xxxxxxxxxxxxxx/ > > Suggested-by: Junio C Hamano <gitster@xxxxxxxxx> > Signed-off-by: Taylor Blau <me@xxxxxxxxxxxx> > --- > Documentation/howto/maintain-git.txt | 16 ++++++++++++++++ > 1 file changed, 16 insertions(+) > > diff --git a/Documentation/howto/maintain-git.txt > b/Documentation/howto/maintain-git.txt > index da31332f11..fd1560327c 100644 > --- a/Documentation/howto/maintain-git.txt > +++ b/Documentation/howto/maintain-git.txt > @@ -165,6 +165,22 @@ 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 Nit: `[notes]` is indented with spaces while the next line is indented with a tab. I guess it’s supposed to just be spaces in this context? > + > + 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 > > base-commit: 3857aae53f3633b7de63ad640737c657387ae0c6 > -- > 2.46.2.633.gf09c3c1769.dirty It might be worth explicitly mentioning the git-cherry-pick(1) footgun that Junio talked about in his email: you have to restrict yourself to git-rebase(1) and `git commit --amend`. Since git-cherry-pick(1) doesn’t care about (respect?) this configuration. Right now it’s implied of course (“when rebasing”). -- Kristoffer Haugsbakk
