mirrors/git
0
0
Fork 0
mirror of https://github.com/git/git.git synced 2024-11-24 02:17:02 +08:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
Taylor Blau 2024-10-02 21:09:56 -04:00 committed by Junio C Hamano
parent 3857aae53f
commit ddfb5bcfc6
1 changed files with 44 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
Documentation/howto/maintain-git.txt
View File

@ -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/heads/next:refs/heads/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