[PATCH RFC] revert: improve warning part of help text

[Adrian Buehlmann]

On 2011-06-06 02:30, Matt Mackall wrote:
> On Mon, 2011-06-06 at 02:02 +0200, Adrian Buehlmann wrote:
>> On 2011-06-06 01:42, Matt Mackall wrote:
>>> On Mon, 2011-06-06 at 01:18 +0200, Adrian Buehlmann wrote:
>>>> # HG changeset patch
>>>> # User Adrian Buehlmann <adrian at cadifra.com>
>>>> # Date 1307258994 -7200
>>>> # Node ID a189aee647f462e3eff219413f5903d7fd2f18f8
>>>> # Parent  b88368a3ade4b748c8e01cf0453158f80e558a7a
>>>> revert: improve warning part of help text
>>>>
>>>> Don't make assumptions about the user's intentions.
>>>>
>>>> diff --git a/mercurial/commands.py b/mercurial/commands.py
>>>> --- a/mercurial/commands.py
>>>> +++ b/mercurial/commands.py
>>>> @@ -4088,13 +4088,13 @@
>>>>  def revert(ui, repo, *pats, **opts):
>>>>      """restore individual files or directories to an earlier state
>>>>  
>>>> -    .. note::
>>>> -       This command is most likely not what you are looking for.
>>>> -       Revert will partially overwrite content in the working
>>>> -       directory without changing the working directory parents. Use
>>>> -       :hg:`update -r rev` to check out earlier revisions, or
>>>> -       :hg:`update --clean .` to undo a merge which has added another
>>>> -       parent.
>>>> +    .. warning::
>>>> +       In contrast to the update command, revert never changes the
>>>> +       parent revisions of the working directory. Revert thus cannot
>>>> +       completely set the working directory state back to an earlier
>>>> +       revision, nor can it undo a merge.
>>>> +       Use :hg:`update -r REV` to check out an earlier revision, or
>>>> +       :hg:`update --clean .` to undo a uncommitted merge.
>>>
>>> You're really overestimating new users here. Hang out on IRC more if you
>>> doubt me. New users don't understand working directories, parent
>>> revisions, or how that all connects to what happens when you commit. And
>>> merges are pure magic.
>>
>> But then we might as well slap the sentence "Read the mercurial book"
>> into every command's help.
> 
> That's hyperbole. It's perfectly reason to put 'danger' signs on things
> that are dangerous without requiring people understand everything about
> a topic.
> 
>> If you (as a user) don't know or don't want to know what the working
>> directory is, then you have to read about the basic concepts first.
>>
>>> All they know is "huh, revert sounds like going backwards (even though I
>>> don't understand this jargon in the warning or even why it's a warning),
>>> I want to go backwards, let's see what happens, oh it wants --all
>>> (annoying!), now it looks like it worked, yay!"
>>>
>>> In fact, most of them probably don't even get as far as reading the
>>> warning, as the summary line is too suggestive of what they want.
>>>
>>> Also note that apparently git revert ~= hg backout.
>>>
>>> SVN's revert command apparently works like ours:
>>>
>>> http://svnbook.red-bean.com/en/1.5/svn.ref.svn.c.revert.html
>>>
>>> ..but they've got the warning at the bottom where it won't help the
>>> fingers-faster-than-brain crowd.
>>
>> I'm still convinced that "This command is most likely not what you are
>> looking for." is unsuitable for the help text of a professional product
>> like Mercurial is.
> 
> I'm not disagreeing. I'm just telling you the (sizable) audience for
> which the warning is intended. They really are completely ignorant of
> what they're doing. If you can find a way to address those users without
> being insulting, great.

Ah. So I take that you agree that the current wording is insulting... !

>> One of the reasons why Mercurial could potentially make users angry.
> 
> Do you REALLY think they'll be less angry when they shoot themselves in
> the foot? I suspect they'll actually be much angrier.

But this is a logical fallacy: you assume that your wording works. I
claim it doesn't work. Users don't understand *why* they shouldn't use
this command. All that sentence accomplishes at best is making users
angry and frustrated. Those who are determined enough will try the
command anyway (possibly *because* they are angry enough to not care any
more).