Junio C Hamano <gitster@xxxxxxxxx> writes:
> The usefulness of the message comes from its information content.
> What do we want to read out of these messages? I think we want
> a title that immediately lets us know three things:
>
> (1) What the original patch was about.
> (2) What the final state is.
> (3) How involved was the road to get to the final state has been.
>
> As to (1), we are not proposing to lose what comes "Revert", so this
> information is not lost under any proposal we have seen so far in
> the discussion.
Agreed.
> As to (2), with the current "Revert" -> "Revert Revert" -> "Revert
> Revert Revert" -> ..., you have to count, which is cumbersome and
> does not give you an immediate access to that information. With
> "Revert^n", you'd see if n is even or odd to determine, which is
> much better than the status quo
I actually think "Revert^n" is much worse than what we have, mainly
because the "^n" syntax is already used in other subcommands (e.g.,
rebase). It may well be that we already have overloaded syntax
elsewhere, but we should avoid overloading where possible.
> , but it takes practice to interpret.
> With "Revert" -> "Reapply" -> "Revert Reapply" -> "Reapply Reapply"
> -> ..., the first word would give you the final state immediately.
I agree. But to take the idea further, maybe "Reapply Reapply" should be
shortened to just
Reapply* "original title"
and likewise any ultimate _removal_ of the commit (no matter the exact
pairwise count of the word "Revert") should be shortened to
Revert* "original title"
? The trailing asterisk in each case would indicate that this
reapplication was not the first reapplication. We could then put
in the commit message body text something like
--8<---------------cut here--------------------------------->8---
*NOTE: This is not the first time we've reverted XXX.
--8<---------------cut here----------------^---------^------>8---
| |
| Commit SHA.
|
Could be "reapplied" if
"Reapply*" is the title
prefix.
to help stress point (3) that you described in your list above.
> We want to know (3), because between a change whose revert was
> reverted and a change that hasn't been involved in any revert, there
> may be no difference in the end result, the former is likely to be
> trickier and merits more careful inspection than the latter.
Agreed.
> With
> "Revert^n", we read how large the number n is to find the
> information. With the current "the Revert repeated number of times"
> or your "a pair of frontmost Reverts become one Reapply", the length
> of the Revert/Reapply prefix conveys this information, but this is
> associated with the cost of pushing the original title further to
> the right and hard to read/find.
I agree that trying to keep the title short is very important. I didn't
think too deeply about this point previously, but I think it is equally
important as the other points you've enumerated above.
> Note that, while the number of
> times revert-reapply sequence took place is a useful piece of
> information, the exact number may not be all that important.
Agreed. For this reason I would prefer just using a single asterisk (as
in my example) after the first occurrence of the revert/reapplication.
> And from the above discussion, I wonder if the following would be a
> good place to stop:
>
> - The first revert is as before: Revert "original title"
> - A revert of a revert becomes: Reapply "original title"
> - A revert of a reapply becomes: Revert Reapply "original title"
> - A revert of "Revert Reapply" becomes: Reapply Reapply "original title"
> - A revert of "Reapply Reapply" becomes: Revert Reapply "original title"
>
> In other words, we accept the fact that wedo not need exact number
> of times reversions were done, and use that to simplify the output
> to make sure we will not spend more than two words in the front of
> the title. That would help to keep the original title visible,
> while still allowing us to distinguish the ones that was reverted up
> to four times (and "Revert Reapply" and "Reapply Reapply" only tell
> us "final state is to (discard|accept) the original but it took us
> _many_ times", without saying exactly how many).
I very much like your idea of just "stopping the recursion" early on.
The only difference is that I would prefer to drop the second "Reapply"
word in your examples and replace them with an asterisk (this makes them
the same as in my example).
I think having this second word "Reapply" would make the title
potentially hurt readability, especially because the first word is
really the only one users should be looking at anyway to figure out the
final state. Another reason for dropping it is because a well-written
commit message title should have a single verb near the beginning, but
your style would break this convention.
If you don't like the "asterisk" idea, another form might be
- A revert of a reapply becomes: Revert reapplication of "original title"
- A revert of the above becomes: Reapply revert of "original title"
- A revert of the above becomes: Revert reapplication of "original title"
- A revert of the above becomes: Reapply revert of "original title"
and so forth.
