Taylor Blau <me@xxxxxxxxxxxx> 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.
