Re: [PATCH v5 00/11] doc: interpret-trailers: explain key format

> Le 9 août 2026 à 16:07, [email protected] a écrit :
> 
> From: Kristoffer Haugsbakk <[email protected]>
> 
> Topic name (applied): kh/doc-trailers
> 
> Topic summary: Explain the format of trailer keys (alphanum and
> hyphens). This is important to keep in mind so that metadata is not
> lost to simple syntax errors. Also replace some terms and define the
> important ones upfront.
> 
> Here one change lead to another in order to make sure that everything
> stayed coherent. So here’s a linear overview of the changes (as of v4):
> 
> • Patches 1–3: remove RFC 822 mentions, “metadata” term
> • Patch 4: This command is not just for commit messages
> • Patches 5–7: Explain the format in the simplest case, explain
>  the “key” format, and add a new example
> • Patch 8: join some existing paragraphs that are about the same theme
>  since that makes the text flow better
> • Patch 9: Also use the “trailer block” term introduced to the doc in
>  patch 5 later in the doc
> • Patch 10: Rewrite new-trailer paragraphs (relates to patch 8)
> • Patch 11: document line comment behavior
> 
> Thanks to everyone who has been reviewing these so far. I understand that
> these eleven changes are very incremental and piecemeal (see “very
> cross-referenced commit messages”). And the commit messages can be quite
> long, just to explain (again) very small changes. See for example patch
> “replace “lines” with “metadata”” in this version, where I explain why to
> write “trailer metadata” instead of “trailers metadata”. But right now I
> feel like prose sometimes needs all this ceremony. With code you get
> restraints like coding style, then you have all the years of looser rules
> about when to use certain data structures, when to make helper methods,
> etc. But with prose it seems that you bring much more of your individuality
> to it. That means more choices, and many of them are not obvious to the
> reader of the document, which means that you need to explain it in the
> commit message. Then you also have to consider the writing history of the
> document, and this one is twelve years old at this point; see the history
> review in commit message “join new-trailers again”, after the thematic
> break (***).
> 
> § Changes in v5
> 
> Patch “document comment line treatment”: commit message: add missing word:
> s/to/to be/.
> 
> § Apologies for very cross-referenced commit messages
> 
> (see v3)
> 
> § Cc
> 
> (see v2)
> 
> https://lore.kernel.org/git/[email protected]/
> 
> I have also added a new email since the email [email protected] bounces
> for me. There is a Brendan Jackman who has posted messages under a Gmail
> address. Hopefully it’s the same person.
> 
> § In-reply-to: v1
> 
> The recommendation to reply to the first version/cover letter is from topic
> ps/doc-recommend-b4, which is in `next` right now.
> 
> § Link to v4
> 
> https://lore.kernel.org/git/[email protected]/
> 
> [01/11] doc: interpret-trailers: stop fixating on RFC 822
> [02/11] doc: interpret-trailers: replace “lines” with “metadata”
> [03/11] doc: interpret-trailers: use “metadata” in Name as well
> [04/11] doc: interpret-trailers: not just for commit messages
> [05/11] doc: interpret-trailers: explain the format after the intro
> [06/11] doc: interpret-trailers: explain key format
> [07/11] doc: interpret-trailers: add key format example
> [08/11] doc: interpret-trailers: join new-trailers again
> [09/11] doc: interpret-trailers: commit to “trailer block” term
> [10/11] doc: interpret-trailers: rewrite new-trailers paragraphs
> [11/11] doc: interpret-trailers: document comment line treatment
> 
> Documentation/git-interpret-trailers.adoc | 88 ++++++++++++++++-------
> 1 file changed, 64 insertions(+), 24 deletions(-)
> 
> Interdiff against v4:
> Range-diff against v4:
> 1:  2419b1a6863 =  1:  2419b1a6863 doc: interpret-trailers: stop fixating on RFC 822
> 2:  859ab42ac41 =  2:  859ab42ac41 doc: interpret-trailers: replace “lines” with “metadata”
> 3:  ab5b4af970e =  3:  ab5b4af970e doc: interpret-trailers: use “metadata” in Name as well
> 4:  b79ddf3b13e =  4:  b79ddf3b13e doc: interpret-trailers: not just for commit messages
> 5:  e7101eb1fcb =  5:  e7101eb1fcb doc: interpret-trailers: explain the format after the intro
> 6:  557b5b5564a =  6:  557b5b5564a doc: interpret-trailers: explain key format
> 7:  eee81fc99fa =  7:  eee81fc99fa doc: interpret-trailers: add key format example
> 8:  cd3e47459c7 =  8:  cd3e47459c7 doc: interpret-trailers: join new-trailers again
> 9:  c50b6d25170 =  9:  c50b6d25170 doc: interpret-trailers: commit to “trailer block” term
> 10:  c11a116605e = 10:  c11a116605e doc: interpret-trailers: rewrite new-trailers paragraphs
> 11:  7d20cb7528f ! 11:  cabbb05a1c4 doc: interpret-trailers: document comment line treatment
>    @@ Commit message
> 
>         Comment lines have always been ignored but this is not documented.
> 
>    -    The primary motivation here is to reasonably complete in the
>    +    The primary motivation here is to be reasonably complete in the
>         documentation of how trailers are parsed; this is after all the only
>         documentation page that documents this format. However, and going beyond
>         that point, we could imagine that someone would want to use this format
> 
> base-commit: 5361983c075154725be47b65cca9a2421789e410
> --
> 2.54.0.22.g9e26862b904

I’m trivially satisfied with the range-diff (note again I’ve reviewed primarily the end result, not the per-commit history).

Best,
Ben