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

From: Stefan Beller <sbeller@google.com>
Date: Mar 13, 2017, 18:00 UTC
Message-ID: <CAGZ79kYedz+r-f7HbDiQR6bfUoUK8LL6g42vO=9uGwHtcPkmhg@mail.gmail.com>
In-Reply-To: <20170312124725.ogwame2nm72maffy@sigill.intra.peff.net>

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