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

From: Oswald Buddenhagen <oswald.buddenhagen@gmx.de>
Date: Aug 11, 2023, 12:49 UTC
Message-ID: <ZNYuUh27ByphTH04@ugly>
In-Reply-To: <owly5y5mh81i.fsf@fine.c.googlers.com>

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

Show 13 quoted lines

>Oswald Buddenhagen <oswald.buddenhagen@gmx.de> 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.

Show 6 quoted lines

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

Show 12 quoted lines

>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