Subject: Re: Comment trailers vs. bracketed lines

From: Junio C Hamano <[email-masked]>
Date: Wed, 07 May 2025 12:20:44 -0700

"Kristoffer Haugsbakk" <[email-masked]> writes:

>> I think in the usual trailer order, it would be:
>>
>>   Signed-off-by: Ramsay
>>   [jk: add commit message]
>>   Signed-off-by: me
>>
>> but I didn't want to forge his S-o-b without asking first.
>
> I’ve seen those brackets in the log.  They used to happen with some
> regularity.  At first it made sense since you need a free-form area to
> both comment and tell everyone that you left the comment.  And a trailer
> doesn’t make sense for that, I thought.[1]
>
> But thinking about the signoff requirement: you already have all the
> information you need from the next trailer, namely the signoff.  In
> other words this:
>
>     [kh: Added tests]
>     Signed-off-by: Kristoffer Haugsbakk <[email-masked]>
>
> Has the same information as this:
>
>     Comment: Added tests
>     Signed-off-by: Kristoffer Haugsbakk <[email-masked]>
>
> Because the signoff order tells you who left the comment.  So I was
> wondering to myself why this uniform approach wasn’t used.

Simply because we already saw another project like the kernel use
the [initial: comment] convention, I think.  The "25% rule" was
originally added specifically to accomdate this kind of comments
frequently used in the kernel project, if I am not mistaken.

We see too many 'jk' and 'js' in the project so the initial may not
be all that meaningful if added and it usually is obvious who did
what without, but even with three letter initial,

    [khh: Added tests]
    Comment: Added tests

the existing convention is still shorter than with your "Comment: "
prefix ;-)