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

[Junio C Hamano <gitster@pobox.com>]

Taylor Blau <me@ttaylorr.com> writes:

> 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>
> Signed-off-by: Taylor Blau <me@ttaylorr.com>
> ---
>  Documentation/howto/maintain-git.txt | 16 ++++++++++++++++
>  1 file changed, 16 insertions(+)

This addition to the procedure part of the documentation reads good.

We'd need a matching addition to "The Policy" part, to describe the
motivation separately.  The procedure exists only to realize what
the policy gives, and we need something to back up the expectation
"to update refs/notes/amlog" (i.e. because there is this policy).

Existig "policy" entries are only about how integration branches are
maintained and used, but notes/amlog are solely about the individual
patches, so we'd need an entirely new section there, I guess.

While at it, I notice that there is no mention on where these notes
are published (the configuration you added to the text is solely
about the local repository the maintainer uses).

I just added this change

 [remote "github2"]
         url = https://github.com/git/git
         fetch = +refs/heads/*:refs/remotes/github2/*
         pushurl = github.com:git/git.git
         push = refs/heads/maint:refs/heads/maint
         push = refs/heads/master:refs/heads/master
         push = refs/heads/next:refs/heads/next
         push = +refs/heads/seen:refs/heads/seen
+        push = +refs/notes/amlog

to github.com/git/git/ and other publishing repositories.  My
broken-out repository github.com/gitster/git/ have been pushed
with the mirror mode, so there needs no change, but others like
k.org repositories will start seeing this additional ref when I push
out today's integration results.

The "policy" part of the change may read like the following.

Thanks.

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

diff --git c/Documentation/howto/maintain-git.txt w/Documentation/howto/maintain-git.txt
index da31332f11..9b72d435e6 100644
--- c/Documentation/howto/maintain-git.txt
+++ w/Documentation/howto/maintain-git.txt
@@ -35,6 +35,14 @@ The maintainer's Git time is spent on three activities.
 The Policy
 ----------
 
+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.
+
 The policy on Integration is informally mentioned in "A Note
 from the maintainer" message, which is periodically posted to
 the mailing list after each feature release is made: