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

[kristofferhaugsbakk@fastmail.com]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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/V2_CV_doc_int-tr_key_format.613@msgid.xyz/

I have also added a new email since the email jackmanb@google.com 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/V4_CV_doc_int-tr_key_format.ae2@msgid.xyz/

[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