Re: [RFC PATCH] help: add optional instructions for reporting bugs

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Mar 10, 2017, 18:13 UTC
Message-ID: <20170310181342.GE26789@aiede.mtv.corp.google.com>
In-Reply-To: <20170309193050.19988-1-sbeller@google.com>

Hi,

Stefan Beller wrote:

Show 8 quoted lines

> When reporting bugs, users will usually look at the output of
> 'git --version' at one point to write a quality bug report.
> So that is a good spot to provide additional information to the user
> about e.g. additional the organizational quirks how to report a bug.
>
> As the output of 'git --version' is parsed by scripts as well,
> we only want to present this information to users, which is why
> we only give the output to TTYs.

Interesting thought. This might also be a good place to point users to "git version --build-options" to get more detailed build information.

The existence of that option also suggests you're on the right track about 'git version' being the command for this.

> Git is distributed in various ways by various organizations. The Git
> community prefers to have bugs reported on the mailing list, whereas
> other organizations may rather want to have filed a bug in a bug tracker
> or such.  The point of contact is different by organization as well.

It's tempting to put the custom information in --build-options --- e.g.

 $ git version
 git version 2.12.0.190.g6e60aba09d.dirty
 hint: use "git version --build-options" for more detail
 hint: and bug reporting instructions
 $
 $ git version --build-options
 git version 2.12.0.190.g6e60aba09d.dirty
 sizeof-long: 8
 reporting-bugs: see REPORTING BUGS section in "git help git"

Using 'hint:' would put this in the advice category. Usually those are possible to disable using advice.* configuration (e.g. advice.versionBuildOptions) for less noisy output.

[...]

Show 7 quoted lines

> --- a/help.c
> +++ b/help.c
> @@ -9,6 +9,12 @@
>  #include "version.h"
>  #include "refs.h"
>  
> +#ifdef GIT_BUG_REPORT_HELP

If doing this for real, there would be a knob in the Makefile for setting the bug report string.

[...]

Show 6 quoted lines

> @@ -435,6 +441,8 @@ int cmd_version(int argc, const char **argv, const char *prefix)
>  			/* NEEDSWORK: also save and output GIT-BUILD_OPTIONS? */
>  		}
>  	}
> +	if (isatty(1))
> +		puts(git_bug_reporting_string);

Should this go to stderr?  E.g. advise() writes to stderr.

Some scripts may run "git version" in output that is written to stdout and meant to be copy/pasted. Is there a way for such scripts to suppress this output? Should they use -c advice.versionBuildOptions=0, does 'git version' need an option to suppress the human-oriented output, should they use 2>/dev/null, or is this just something that people have to live with?

I'm still on the fence about whether this is a good idea. At least having custom bug instructions in --build-options sounds like a very nice thing, but it's not obvious to me how people would learn about that option.

Thanks and hope that helps, Jonathan