Subject: Re: [PATCH v3 2/2] doc: revert: add discussion

From: Oswald Buddenhagen <[email-masked]>
Date: Fri, 11 Aug 2023 14:49:22 +0200

On Thu, Aug 10, 2023 at 02:50:59PM -0700, Linus Arver wrote:
>Nit: the "doc: revert: add discussion" subject line should probably be more
>like "revert doc: suggest adding the 'why' behind reverts".
>
this is counter to the prevalent "big endian" prefix style, and is in 
this case really easy to misread.
i also intentionally kept the subject generic, because the content 
covers two matters (the reasoning and the subjects, which is also the 
reason why this is a separate patch to start with).

>Oswald Buddenhagen <[email-masked]> writes:
>> +DISCUSSION
>> +----------
>> +
>> +While git creates a basic commit message automatically, you really
>> +should not leave it at that. In particular, it is _strongly_
>> +recommended to explain why the original commit is being reverted.
>> +Repeatedly reverting reversions yields increasingly unwieldy
>> +commit subjects; latest when you arrive at 'Reapply "Reapply
>> +"<original subject>""' you should get creative.
>
>The word "latest" here sounds odd. Ditto for "get creative".
>
yeah, i suppose. i wasn't sure how formal i should make it - things 
aren't consistent to start with.

> How about the following rewording?
>
>    While git creates a basic commit message automatically, it is
>    _strongly_ recommended to explain why the original commit is being
>    reverted. In addition, repeatedly reverting the same commit will
>    result in increasingly unwieldy subject lines,

>for example 'Reapply "Reapply "<original subject>""'.
>
you turned it from a suggested threshold into an example. at this point 
it appears superfluous to me.

>Please consider rewording such
>    subject lines to reflect the reason why the original commit is being
>    reapplied again.
>
the reasoning most likely wouldn't fit into the subject.
also, the original request to explain the reasoning applies 
transitively, so i don't think it's really necessary to point it out 
explicitly.

On Thu, Aug 10, 2023 at 03:00:41PM -0700, Linus Arver wrote:
>Hmph, "repeatedly reverting the same commit" sounds wrong because
>strictly speaking there is only 1 "same commit" (the original commit).
>Perhaps
>
>    In addition, repeatedly reverting the same progression of reverts will
>
>or even
>
>    In addition, repeatedly reverting the same revert chain will
>
>is better here?
>
we used "recursive reverts" elsewhere. but i'm not sure whether that's 
sufficiently intuitive and formally correct.

anyway, what's wrong with my original proposal?

so in summary, how about:

     While git creates a basic commit message automatically, it is
     _strongly_ recommended to explain why the original commit is being
     reverted. In addition, repeatedly reverting reversions will
     result in increasingly unwieldy subject lines. Please consider 
     rewording these into something shorter and more unique.

regards