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

Phillip Wood [off-list ref] writes:

On 10/08/2023 22:50, Linus Arver wrote:

quoted

Oswald Buddenhagen [off-list ref] writes:

quoted

+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". 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>""'. Please consider rewording such
     subject lines to reflect the reason why the original commit is being
     reapplied again.

That's a good suggestion, I think having the example will help readers
understand the issue being described.

Sounds very good.