From: Junio C Hamano Date: Mon, 30 Mar 2026 21:55:27 GMT Subject: Re: [PATCH 2/2] doc: interpret-trailers: explain key format Message-ID: In-Reply-To: kristofferhaugsbakk@fastmail.com writes: > From: Kristoffer Haugsbakk > > A trailer key must consist of ASCII alphanumeric characters and > hyphens *only*. Let’s document it explicitly instead of relying on > readers being conservative and painting their trailers by numbers > (by the documentation examples). "paint"? I am not sure what the latter half of the above paragraph wants to say, even though I do agree that being explicit about the allowed characters is a good idea. > The previous commit for “key–value pairs” allows us to segue right into > describing these lines as consisting of a key and a value, which is our > opening to describing the key format. And it is a good place to remedy the issue I raised for the previous step as well ;-) > Just like *trailer* we emphasize these two first standalone word > mentions. Again, I have no idea what "these two first standalone word" wants to refer to. It is not even clear to me if it refers to a single thing, or two things---the verb "mentions" hints that the subject of the sentence must be plural, but I cannot tell what two things you are referring to. > diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc > index e7c1f821619..92d9c95f9d2 100644 > --- a/Documentation/git-interpret-trailers.adoc > +++ b/Documentation/git-interpret-trailers.adoc > @@ -27,7 +27,10 @@ Signed-off-by: Alice > Signed-off-by: Bob > ------------------------------------------------ > > -the last two lines starting with `Signed-off-by` are trailers. > +the last two lines starting with `Signed-off-by` are trailers. These two > +trailers have the _key_ `Signed-off-by` and a _value_ (Alice and Bob). Remedy the loss of "e-mail like" by ending the above sentence more like: ... and Bob), with a colon appended at the end of the key. > +The key must consist of only ASCII alphanumeric characters and hyphens > +(`-`). The hyphens serve as interword separators. The first sentence is a very much welcome addition. I however doubt that the last sentence is necessary or beneficial, as "SignedOffBy" is a perfectly fine key to be used for a trailer if a project prefers (not this project, though). I would not object to The hyphens can be used as inter-word separators. or The hyphens can be used as inter-word separators, if you want. but any expression that can be misinterpreted that the document strongly suggests projects and communities to adopt the "hyphen as inter-word separator" convention is not very welcome. Thanks.