| Message ID | a4b1da93e16d88323181f8f8444f01d96e09ef45.1727729100.git.me@ttaylorr.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Documentation: mention the amlog in howto/maintain-git.txt | expand |
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@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(+) > > 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”).
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:
On Mon, Sep 30, 2024 at 11:06:03PM +0200, Kristoffer Haugsbakk wrote: > > @@ -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? Oops, good catch, thanks. > 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. I think that's worth mentioning, and I added a small tidbit in the latest round mentioning it, thanks. Thanks, Taylor
On Mon, Sep 30, 2024 at 02:54:23PM -0700, Junio C Hamano wrote: > 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: Thanks, this looks good to me, and I added it in the latest version of this patch, with your Helped-by. I moved this section to the end of the this section, not the beginning, since it seems more important to first discuss the mechanics of topic branches, next, seen, master, etc., before getting to the nuts and bolts of the amlog ;-). Thanks, Taylor
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 + + 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
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(+) base-commit: 3857aae53f3633b7de63ad640737c657387ae0c6