Re: [PATCH v2] Documentation: mention the amlog in howto/maintain-git.txt

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 2, 2024, 19:47 UTC
Message-ID: <xmqq8qv6l226.fsf@gitster.g>
In-Reply-To: <5cc8e2bcb88424d8dce526f518282e4b26a1760a.1727881364.git.me@ttaylorr.com>

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".

Show 8 quoted lines

> +   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.