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

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 11, 2023, 19:43 UTC
Message-ID: <xmqq1qg9s6uj.fsf@gitster.g>
In-Reply-To: <ZNZ7GhVkLuwYOPij@ugly>

Oswald Buddenhagen <oswald.buddenhagen@gmx.de> writes:

> make this fully orthogonal to reverting reverts in particular (note
> that i attached it to the generic "discussion" patch rather than the
> "reverts of reverts" one).

I viewed that as a patch to add "discussion on how to explain revert" (not necessarily "revert of revert", but how "revert" in general should be explained).

> i didn't think about the integration with existing options yet.

Now I did ;-).

The discussion of what the right way to present and justify a revert was done before, and I think revert.reference and the "--reference" option came out of it. It aims the same "do not just describe the fact what was reverted, but you should explain why" spirit. While what I showed in my illustration patch was not meant as "integration with existing options", it is inevitable that reuse of existing code that was written earlier for improving the workflow in the same spirit may get involved.

Perhaps we should also tweak the commit log template to give a gentle knudge to the user to use revert.reference and then enhance the help text we give.

Instead of

    Revert "doc: revert: add discussion"

    This reverts commit 7139d1298993b0148ad429cd7cb4824223b7f420.

you may see something along the lines of ...

    # Consider retitling to reflect WHY you are reverting.
    # You may also want to set revert.reference configuration to
    # help encuraging a better title for revert commits.
    Revert "doc: revert: add discussion"

    This reverts commit 7139d1298993b0148ad429cd7cb4824223b7f420
    because <REASON OF REVERSION HERE>

I ran out of time budget for today to think about a topic that is not releant to the current release, so I'd stop here.

THanks.