Re: [PATCH 2/2] doc: interpret-trailers: explain key format
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Mar 30, 2026, 21:55 UTC
- Message-ID
- <xmqqh5px6kz4.fsf@gitster.g>
- In-Reply-To
- <doc_int-tr_not_rfc.535@msgid.xyz>
kristofferhaugsbakk@fastmail.com writes:
Show 6 quoted lines
> From: Kristoffer Haugsbakk <code@khaugsbakk.name> > > 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.
Show 11 quoted lines
> 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 <alice@example.com> > Signed-off-by: Bob <bob@example.com> > ------------------------------------------------ > > -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.