Re: [PATCH 1/4] usability: don't ask questions if no reply is required

From: Jonathan Nieder <jrnieder@gmail.com>
Date: May 3, 2017, 16:47 UTC
Message-ID: <20170503164744.GY28740@aiede.svl.corp.google.com>
In-Reply-To: <20170503162931.30721-1-jn.avila@free.fr>

Hi,

Jean-Noel Avila wrote:

> As described in the bug report at
>
> https://github.com/git/git-scm.com/issues/999

External issue tracker URLs have been known to change or disappear and we try to make commit messages self-contained instead of relying on them. It is common to put a 'Requested-by:' footer or sentence saying 'Requested at <url> by <person>' near the bottom of a commit message for attribution and context. Relying on the bug report more heavily like this example (instead of including any relevant information) makes it harder for a reader to understand the patch easily in one place.

In other words, instead of asking the reader to read the bug report, please include pertinent information the reader needs to understand the patch here so they don't have to.

Show 29 quoted lines

> the user was disconcerted by the question asked by the program not
> requiring a reply from the user. To improve the general usability of
> the Git suite, The following rule was applied:
>
> if the sentence
>  * appears in a non-interactive session
>  * is printed last before exit
>  * is a question addressing the user ("you")
>
> the sentence is turned into affirmative and proposes the option.
>
> Signed-off-by: Jean-Noel Avila <jn.avila@free.fr>
> ---
>  help.c | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/help.c b/help.c
> index bc6cd19cf..4658a55c6 100644
> --- a/help.c
> +++ b/help.c
> @@ -411,8 +411,8 @@ const char *help_unknown_cmd(const char *cmd)
>  
>  	if (SIMILAR_ENOUGH(best_similarity)) {
>  		fprintf_ln(stderr,
> -			   Q_("\nDid you mean this?",
> -			      "\nDid you mean one of these?",
> +			   Q_("\nThe most approaching command is",
> +			      "\nThe most approaching commands are",
>  			   n));

For what it's worth, I find the new text harder to understand than the old text.

From the bug report:

	Now git says git: 'stahs' is not a git command. See 'git --help'.
	Did you mean this?

	stash

	Git asked if i meant git stash. and i entered yes. and git
	printed the character y infinite times.

If I'm reading that correctly, the problem is not that questions are alarming but that Git did not cope well with the answer. When I try to reproduce it, I get

	$ git stahs
	WARNING: You called a Git command named 'stahs', which does not exist.
	Continuing under the assumption that you meant 'stash'
	in 5.0 seconds automatically...

which is much clearer. After commenting out "[help] autocorrect = 50" in my ~/.config/git/config, I get

	$ git stahs
	git: 'stahs' is not a git command. See 'git --help'.

	Did you mean this?
		stash

which does seem improvable, at least for consistency with the autocorrect case. For example, would something like

	$ git stahs
	fatal: You called a Git command named 'stahs', which does not exist.
	hint: Did you mean 'git stash'?

work better?  And the autocorrect case could say something like

	$ git stahs
	warning: You called a Git command named 'stahs', which does not exist.
	warning: Continuing under the assumption that you meant 'stash'
	warning: in 5.0 seconds automatically...

Is contact information for the bug reporter available so we can try out different wordings and see what works for them?

Thanks and hope that helps, Jonathan