Subject: Re: [PATCH] revert: optionally refer to commit in the "reference" format

From: Ævar Arnfjörð Bjarmason <[email-masked]>
Date: Tue, 24 May 2022 10:12:15 +0200

On Mon, May 23 2022, Junio C Hamano wrote:

> Ævar Arnfjörð Bjarmason <[email-masked]> writes:
>
>>> +		if (!opts->commit_use_reference) {
>>> +			strbuf_addstr(&msgbuf, "Revert \"");
>>> +			strbuf_addstr(&msgbuf, msg.subject);
>>> +			strbuf_addstr(&msgbuf, "\"");
>>> +		} else {
>>> +			strbuf_addstr(&msgbuf, "DESCRIBE WHY WE ARE REVERTING HERE");
>>
>> Having seen how people use git in the wild, this *WILL* result in a
>> bunch of history where people don't edit that at all.
>
> It was done very much on purpose.  A pressure from other project
> participants against the ugly all caps content-free message will
> help instill better behaviour.

In some cases that will happen, but from experience of working with a
bunch of novice git users some people won't edit these at all,
particularly when they're in a rush (e.g. reverting something because a
thing broke production).

So making the default subject less useful is something that will be seen
by others, and thus result in worse UX.

AFAICT all of the goals you're suggesting here will be even better if
it's commented out, then you will need to edit it, and we'll error out
by default if you don't. Why not use that?

> A solo developer also will learn
> after making reverts with content-free titles (and if they do not
> find it inconvenient for their development purpose that their
> history is full of content-free titles shouting in all caps, then
> more power to them---if they are happy, we are happy, too).

The subject you're replacing isn't content-free, it at least includes
the OID, this one doesn't, so you won't see it in --oneline. That's less
useful.

> If we leave something like
>
> 	# Add one line above and explain not *what* this revert did,
> 	# but *why* you decided to revert in 50-70 chars.  Did it
> 	# break something? Was it premature?
>
> 	This reverts commit 8aa3f0dc (CI: set CC in MAKEFLAGS directly, 2022-04-21)
>
> presumably, stripspace will make the "This reverts commit ..." the
> title of the reverted commit.  It would invite people not to edit it
> out out of laziness.  Since the whole point of this change is to
> encourage people to describe the reason behind the revert on the
> subject line, such an invitation is counter-productive.

If that's the concern we could also comment the "This reverts" line.

> Doing the first two lines like so:
>
> 	Revert 8aa3f0dc (CI: set CC in MAKEFLAGS directly, 2022-04-21)
> 	# Edit the above line to explain not *what* this revert did,
>
> would have pretty much the same effect, I am afraid.
>
> So...

Ditto, so just present a buffer like:

    # Revert 8aa3f0dc (CI: set CC in MAKEFLAGS directly, 2022-04-21)
    #
    # This reverts commit 8aa3f0dc (CI: set CC in MAKEFLAGS directly, 2022-04-21)

Along with some advice that the user can uncomment those template lines
& adjust them.