Re: [PATCH 2/2] doc: interpret-trailers: explain key format

["Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com>]

On Mon, Mar 30, 2026, at 23:55, Junio C Hamano wrote:
> kristofferhaugsbakk@fastmail.com writes:
>
>> 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.

“Paint by numbers”, “paint inside the lines.” Using the docs as a guide
to create very similar-looking keys. Contrast with the original issue
here:

    Basically, as soon as any trailer key contains a period (which in my
    case, it does because the trailer keys refer to versions of of
    software, i.e. "this commit was backported from the following Linux
    kernel commit which appeared in version 6.1"), [...]

A symptom of taking the examples from the doc and adding just a little
extra to it.

This cutesy phrasing can be dropped. We’ll see.

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

Key & value.

Something like:

    Just like *trailer* we emphasize these two first standalone word
    mentions (key and value).

They are the only emphasized words in the diff. Although I *have* relied
too much on the diff context before.

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

Okay. I’ll try with:

    ... and Bob), with a colon separating the key and the value.

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

I’ll take the first one here.

Thank you!