Re: [RFC PATCH] help: add optional instructions for reporting bugs
- From
Christian Couder <christian.couder@gmail.com>
- Date
- Mar 10, 2017, 21:50 UTC
- Message-ID
- <CAP8UFD0xCCcmd66ChsfxPBFohekucBx3ib4Ayi+KQOXNZFHMjQ@mail.gmail.com>
- In-Reply-To
- <20170310181342.GE26789@aiede.mtv.corp.google.com>
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.