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

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

[Stefan Beller]

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.

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.

Signed-off-by: Stefan Beller <sbeller@google.com>
---

Not sure if this is a good idea at all, hence RFC.

Thanks,
Stefan

 help.c | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/help.c b/help.c
index bc6cd19cf3..d4c1fbe5cb 100644
--- a/help.c
+++ b/help.c
@@ -9,6 +9,12 @@
 #include "version.h"
 #include "refs.h"
 
+#ifdef GIT_BUG_REPORT_HELP
+const char git_bug_reporting_string[] = GIT_BUG_REPORT_HELP;
+#else
+const char git_bug_reporting_string[] = "To report bugs send a plain text email to git@vger.kernel.org";
+#endif
+
 void add_cmdname(struct cmdnames *cmds, const char *name, int len)
 {
 	struct cmdname *ent;
@@ -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);
 	return 0;
 }
 
-- 
2.12.0.190.g6e60aba09d.dirty

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

[Jonathan Nieder]

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

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

[Christian Couder]

On Fri, Mar 10, 2017 at 7:13 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:
> 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.

It looks like there is no documentation for `git version` which is a
bit unfortunate.
Also `git version -h` ignores the -h option so we cannot know that
--build-options exists.

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

I agree, but I don't think --build-options is the best for that.

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

I don't think it's a good idea to add those "hint: ..." and
"reporting-bugs: ..." lines.

I think it's better to do things like the following:

- add `git version -h`
- add proper documentation for `git version` so that `git help version` works
- in `git help version` talk about the REPORTING BUGS section in `git help git`
- add `git version --full` or other such options to also print other
stuff like the current OS, processor architecture, libc, etc
- suggest in `git help version` and/or in the REPORTING BUGS section
in `git help git` that people just copy paste the output of `git
version --full` in their bug report

[...]

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

Yeah indeed.

Thanks,
Christian.

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

[Jeff King]

On Fri, Mar 10, 2017 at 10:50:50PM +0100, Christian Couder wrote:

> I don't think it's a good idea to add those "hint: ..." and
> "reporting-bugs: ..." lines.
> 
> I think it's better to do things like the following:
> 
> - add `git version -h`
> - add proper documentation for `git version` so that `git help version` works
> - in `git help version` talk about the REPORTING BUGS section in `git help git`
> - add `git version --full` or other such options to also print other
> stuff like the current OS, processor architecture, libc, etc
> - suggest in `git help version` and/or in the REPORTING BUGS section
> in `git help git` that people just copy paste the output of `git
> version --full` in their bug report

I wonder if a "gitbugs(7)" manpage would be a good thing. Then "git help
bugs" would find it.

That still leaves open the question of whether people would find that
documentation, but at least it is less buried than being at the bottom
of the git(1) page.

-Peff

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

[Stefan Beller]

On Sun, Mar 12, 2017 at 5:47 AM, Jeff King <peff@peff.net> wrote:
> On Fri, Mar 10, 2017 at 10:50:50PM +0100, Christian Couder wrote:
>
>> I don't think it's a good idea to add those "hint: ..." and
>> "reporting-bugs: ..." lines.
>>
>> I think it's better to do things like the following:
>>
>> - add `git version -h`
>> - add proper documentation for `git version` so that `git help version` works
>> - in `git help version` talk about the REPORTING BUGS section in `git help git`
>> - add `git version --full` or other such options to also print other
>> stuff like the current OS, processor architecture, libc, etc
>> - suggest in `git help version` and/or in the REPORTING BUGS section
>> in `git help git` that people just copy paste the output of `git
>> version --full` in their bug report
>
> I wonder if a "gitbugs(7)" manpage would be a good thing. Then "git help
> bugs" would find it.
>
> That still leaves open the question of whether people would find that
> documentation, but at least it is less buried than being at the bottom
> of the git(1) page.

To do it right(tm), I assume we have all of the mentioned ways;
all of them pointing at the same document.

I am on the fence if we want to have a gitbugs and gitversion man page,
precisely because I'd expect these instructions to be overwritten
by downstream users (e.g. all of the 255 linux distributions would put
their own bug tracker there, iff they carry additional patches; so would
we internally as we do have a couple of patches on top of next.)

It might be not as bad for git as it is for the kernel with tainted modules
such that my worries may be unreasonable.

Thanks,
Stefan