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

[Jonathan Nieder <jrnieder@gmail.com>]

Hi,

Stefan Beller wrote:

> 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.

[...]
> --- 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.

[...]
> @@ -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