| Message ID | 5cc8e2bcb88424d8dce526f518282e4b26a1760a.1727881364.git.me@ttaylorr.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | [v2] Documentation: mention the amlog in howto/maintain-git.txt | expand |
Taylor Blau <me@ttaylorr.com> writes: Now the policy explains what is done (i.e. amlog gives a mapping) and for what purpose (i.e. we want to be able to go back to the origin), "... is expected to" in the actual procedure is redundant. In other words, the procedure section can focus on what is done without repeating why. > + 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. I'd replace the above with something like: Applying the e-mailed patches using "git am" automatically records the mappings from Message-Id to resulting commit in the "amlog" note. 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 "created" -> "maintained". > + 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'). "(note ...)" -> 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. The purpose of pushing amlog out does not need to be repeated here in the procedure section. Make sure that push refspec for refs/notes/amlog is in the remote configuration for publishing repositories. A few sample .git/config entries may look like this: [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 [remote "github"] url = https://github.com/gitster/git pushurl = github.com:gitster/git.git mirror Other than that, nicely done. Thanks for filling the gap in the documentation.
diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt index da31332f11..76d6688d4c 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,24 @@ 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 + + (note that this configuration is not read by 'cherry-pick'). + + 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