threads / rfc / 45331

RFC patchhelp: add optional instructions for reporting bugs

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

## tl;dr

5 messages between Mar 9, 2017 and Mar 13, 2017. Diffs are folded; open one to read it.

replies: 4people: 4as markdown or json

Stefan Beller· Mar 9, 2017, 19:30 UTC · lore

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(+)

Show changes to help.c +8 −0

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

Jonathan Nieder· Mar 10, 2017, 18:13 UTC · re: Stefan Beller · lore

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

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

Christian Couder· Mar 10, 2017, 21:50 UTC · re: Jonathan Nieder · lore

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

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

Show 16 quoted lines

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

Show 16 quoted lines

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

Jeff King· Mar 12, 2017, 12:47 UTC · re: Christian Couder · lore

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

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

Show 13 quoted lines

> 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

Stefan Beller· Mar 13, 2017, 18:00 UTC · re: Jeff King · lore

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

On Sun, Mar 12, 2017 at 5:47 AM, Jeff King <peff@peff.net> wrote:

Show 22 quoted lines

> 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