diff mbox series

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

Message ID 88a13b9f2b6e7fbed517a7e268e4e371d84a9a10.1727917792.git.me@ttaylorr.com (mailing list archive)
State New
Headers show
Series [v3] Documentation: mention the amlog in howto/maintain-git.txt | expand

Commit Message

Taylor Blau Oct. 3, 2024, 1:09 a.m. UTC 
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>
---
 Documentation/howto/maintain-git.txt | 44 ++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)


Range-diff against v2:
1:  5cc8e2bcb88 ! 1:  88a13b9f2b6 Documentation: mention the amlog in howto/maintain-git.txt
    @@ Documentation/howto/maintain-git.txt: 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.
    ++   Applying the e-mailed patches using "git am" automatically records
    ++   the mappings from 'Message-Id' to the applied commit in the "amlog"
    ++   notes. Periodically check that this is working with "git show -s
    ++   --notes=amlog $commit".
     +
    -+   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:
    ++   This mapping is maintained 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').
    ++   Avoid "cherry-pick", as it does not propagate notes by design. Use
    ++   either "git commit --amend" or "git rebase" to make corrections to
    ++   an existing commit, even for a single-patch topic.
     +
    -+   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.
    ++   Make sure that a push refspec for 'refs/notes/amlog' is in the
    ++   remote configuration for publishing repositories. A few sample
    ++   configurations look like the following:
    ++
    ++      [remote "github"]
    ++        url = https://github.com/gitster/git
    ++        pushurl = github.com:gitster/git.git
    ++        mirror
    ++
    ++      [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/notes/next:refs/notes/next
    ++        push = +refs/heads/seen:refs/heads/seen
    ++        push = +refs/notes/amlog
     +
       - Review the last issue of "What's cooking" message, review the
         topics ready for merging (topic->master and topic->maint).  Use

base-commit: 3857aae53f3633b7de63ad640737c657387ae0c6

Comments

Junio C Hamano Oct. 3, 2024, 5:23 p.m. UTC | #1 
Taylor Blau <me@ttaylorr.com> writes:

> (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].)

Thanks.
Ramsay Jones Oct. 3, 2024, 6:32 p.m. UTC | #2 
On 03/10/2024 02:09, 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>
> Helped-by: Junio C Hamano <gitster@pobox.com>
> Signed-off-by: Taylor Blau <me@ttaylorr.com>
> ---
>  Documentation/howto/maintain-git.txt | 44 ++++++++++++++++++++++++++++
>  1 file changed, 44 insertions(+)
> 
> diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt
> index da31332f113..f52f32eda93 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,43 @@ by doing the following:
>     In practice, almost no patch directly goes to 'master' or
>     'maint'.
>  
> +   Applying the e-mailed patches using "git am" automatically records
> +   the mappings from 'Message-Id' to the applied commit in the "amlog"
> +   notes. Periodically check that this is working with "git show -s
> +   --notes=amlog $commit".
> +
> +   This mapping is maintained 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
> +
> +   Avoid "cherry-pick", as it does not propagate notes by design. Use
> +   either "git commit --amend" or "git rebase" to make corrections to
> +   an existing commit, even for a single-patch topic.
> +
> +   Make sure that a push refspec for 'refs/notes/amlog' is in the
> +   remote configuration for publishing repositories. A few sample
> +   configurations look like the following:
> +
> +      [remote "github"]
> +        url = https://github.com/gitster/git
> +        pushurl = github.com:gitster/git.git
> +        mirror
> +
> +      [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/notes/next:refs/notes/next

Hmm, s/notes/heads/g perhaps?

> +        push = +refs/heads/seen:refs/heads/seen
> +        push = +refs/notes/amlog
> +
>   - 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
> 

ATB,
Ramsay Jones
Taylor Blau Oct. 3, 2024, 6:44 p.m. UTC | #3 
On Thu, Oct 03, 2024 at 07:32:04PM +0100, Ramsay Jones wrote:
> > +      [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/notes/next:refs/notes/next
>
> Hmm, s/notes/heads/g perhaps?

Ugh, serves me right for trying to send this out late my time last
night.

Perhaps Junio can tweak this when applying? Otherwise I can send out a
new version.

Thanks,
Taylor
diff mbox series

Patch

diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt
index da31332f113..f52f32eda93 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,43 @@  by doing the following:
    In practice, almost no patch directly goes to 'master' or
    'maint'.
 
+   Applying the e-mailed patches using "git am" automatically records
+   the mappings from 'Message-Id' to the applied commit in the "amlog"
+   notes. Periodically check that this is working with "git show -s
+   --notes=amlog $commit".
+
+   This mapping is maintained 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
+
+   Avoid "cherry-pick", as it does not propagate notes by design. Use
+   either "git commit --amend" or "git rebase" to make corrections to
+   an existing commit, even for a single-patch topic.
+
+   Make sure that a push refspec for 'refs/notes/amlog' is in the
+   remote configuration for publishing repositories. A few sample
+   configurations look like the following:
+
+      [remote "github"]
+        url = https://github.com/gitster/git
+        pushurl = github.com:gitster/git.git
+        mirror
+
+      [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/notes/next:refs/notes/next
+        push = +refs/heads/seen:refs/heads/seen
+        push = +refs/notes/amlog
+
  - 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