{"thread":{"id":"45331","subject":"[RFC PATCH] help: add optional instructions for reporting bugs","startedAt":"2017-03-09T19:31:01Z","lastAt":"2017-03-13T18:00:46Z","messageCount":5,"participants":["Stefan Beller","Jonathan Nieder","Christian Couder","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"313670","messageId":"20170309193050.19988-1-sbeller@google.com","threadId":"45331","inReplyTo":null,"subject":"[RFC PATCH] help: add optional instructions for reporting bugs","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-03-09T19:30:50Z","receivedAt":"2017-03-09T19:31:01Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"Git is distributed in various ways by various organizations. The Git\ncommunity prefers to have bugs reported on the mailing list, whereas\nother organizations may rather want to have filed a bug in a bug tracker\nor such.  The point of contact is different by organization as well.\n\nWhen reporting bugs, users will usually look at the output of\n'git --version' at one point to write a quality bug report.\nSo that is a good spot to provide additional information to the user\nabout e.g. additional the organizational quirks how to report a bug.\n\nAs the output of 'git --version' is parsed by scripts as well,\nwe only want to present this information to users, which is why\nwe only give the output to TTYs.\n\nSigned-off-by: Stefan Beller <sbeller@google.com>\n---\n\nNot sure if this is a good idea at all, hence RFC.\n\nThanks,\nStefan\n\n help.c | 8 ++++++++\n 1 file changed, 8 insertions(+)\n\ndiff --git a/help.c b/help.c\nindex bc6cd19cf3..d4c1fbe5cb 100644\n--- a/help.c\n+++ b/help.c\n@@ -9,6 +9,12 @@\n #include \"version.h\"\n #include \"refs.h\"\n \n+#ifdef GIT_BUG_REPORT_HELP\n+const char git_bug_reporting_string[] = GIT_BUG_REPORT_HELP;\n+#else\n+const char git_bug_reporting_string[] = \"To report bugs send a plain text email to git@vger.kernel.org\";\n+#endif\n+\n void add_cmdname(struct cmdnames *cmds, const char *name, int len)\n {\n \tstruct cmdname *ent;\n@@ -435,6 +441,8 @@ int cmd_version(int argc, const char **argv, const char *prefix)\n \t\t\t/* NEEDSWORK: also save and output GIT-BUILD_OPTIONS? */\n \t\t}\n \t}\n+\tif (isatty(1))\n+\t\tputs(git_bug_reporting_string);\n \treturn 0;\n }\n \n-- \n2.12.0.190.g6e60aba09d.dirty\n\n"},{"id":"313764","messageId":"20170310181342.GE26789@aiede.mtv.corp.google.com","threadId":"45331","inReplyTo":"20170309193050.19988-1-sbeller@google.com","subject":"Re: [RFC PATCH] help: add optional instructions for reporting bugs","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2017-03-10T18:13:42Z","receivedAt":"2017-03-10T18:13:50Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi,\n\nStefan Beller wrote:\n\n> When reporting bugs, users will usually look at the output of\n> 'git --version' at one point to write a quality bug report.\n> So that is a good spot to provide additional information to the user\n> about e.g. additional the organizational quirks how to report a bug.\n>\n> As the output of 'git --version' is parsed by scripts as well,\n> we only want to present this information to users, which is why\n> we only give the output to TTYs.\n\nInteresting thought.  This might also be a good place to point users\nto \"git version --build-options\" to get more detailed build\ninformation.\n\nThe existence of that option also suggests you're on the right track\nabout 'git version' being the command for this.\n\n> Git is distributed in various ways by various organizations. The Git\n> community prefers to have bugs reported on the mailing list, whereas\n> other organizations may rather want to have filed a bug in a bug tracker\n> or such.  The point of contact is different by organization as well.\n\nIt's tempting to put the custom information in --build-options --- e.g.\n\n $ git version\n git version 2.12.0.190.g6e60aba09d.dirty\n hint: use \"git version --build-options\" for more detail\n hint: and bug reporting instructions\n $\n $ git version --build-options\n git version 2.12.0.190.g6e60aba09d.dirty\n sizeof-long: 8\n reporting-bugs: see REPORTING BUGS section in \"git help git\"\n\nUsing 'hint:' would put this in the advice category. Usually those are\npossible to disable using advice.* configuration (e.g.\nadvice.versionBuildOptions) for less noisy output.\n\n[...]\n> --- a/help.c\n> +++ b/help.c\n> @@ -9,6 +9,12 @@\n>  #include \"version.h\"\n>  #include \"refs.h\"\n>  \n> +#ifdef GIT_BUG_REPORT_HELP\n\nIf doing this for real, there would be a knob in the Makefile for\nsetting the bug report string.\n\n[...]\n> @@ -435,6 +441,8 @@ int cmd_version(int argc, const char **argv, const char *prefix)\n>  \t\t\t/* NEEDSWORK: also save and output GIT-BUILD_OPTIONS? */\n>  \t\t}\n>  \t}\n> +\tif (isatty(1))\n> +\t\tputs(git_bug_reporting_string);\n\nShould this go to stderr?  E.g. advise() writes to stderr.\n\nSome scripts may run \"git version\" in output that is written to stdout\nand meant to be copy/pasted.  Is there a way for such scripts to\nsuppress this output?  Should they use -c\nadvice.versionBuildOptions=0, does 'git version' need an option to\nsuppress the human-oriented output, should they use 2>/dev/null, or is\nthis just something that people have to live with?\n\nI'm still on the fence about whether this is a good idea. At least\nhaving custom bug instructions in --build-options sounds like a very\nnice thing, but it's not obvious to me how people would learn about\nthat option.\n\nThanks and hope that helps,\nJonathan\n"},{"id":"313801","messageId":"CAP8UFD0xCCcmd66ChsfxPBFohekucBx3ib4Ayi+KQOXNZFHMjQ@mail.gmail.com","threadId":"45331","inReplyTo":"20170310181342.GE26789@aiede.mtv.corp.google.com","subject":"Re: [RFC PATCH] help: add optional instructions for reporting bugs","fromName":"Christian Couder","fromEmail":"christian.couder@gmail.com","sentAt":"2017-03-10T21:50:50Z","receivedAt":"2017-03-10T21:51:05Z","isPatch":true,"sender":{"key":"christian.couder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/208954?v=4"},"body":"On Fri, Mar 10, 2017 at 7:13 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:\n> Hi,\n>\n> Stefan Beller wrote:\n>\n>> When reporting bugs, users will usually look at the output of\n>> 'git --version' at one point to write a quality bug report.\n>> So that is a good spot to provide additional information to the user\n>> about e.g. additional the organizational quirks how to report a bug.\n>>\n>> As the output of 'git --version' is parsed by scripts as well,\n>> we only want to present this information to users, which is why\n>> we only give the output to TTYs.\n>\n> Interesting thought.  This might also be a good place to point users\n> to \"git version --build-options\" to get more detailed build\n> information.\n\nIt looks like there is no documentation for `git version` which is a\nbit unfortunate.\nAlso `git version -h` ignores the -h option so we cannot know that\n--build-options exists.\n\n> The existence of that option also suggests you're on the right track\n> about 'git version' being the command for this.\n\nI agree, but I don't think --build-options is the best for that.\n\n>> Git is distributed in various ways by various organizations. The Git\n>> community prefers to have bugs reported on the mailing list, whereas\n>> other organizations may rather want to have filed a bug in a bug tracker\n>> or such.  The point of contact is different by organization as well.\n>\n> It's tempting to put the custom information in --build-options --- e.g.\n>\n>  $ git version\n>  git version 2.12.0.190.g6e60aba09d.dirty\n>  hint: use \"git version --build-options\" for more detail\n>  hint: and bug reporting instructions\n>  $\n>  $ git version --build-options\n>  git version 2.12.0.190.g6e60aba09d.dirty\n>  sizeof-long: 8\n>  reporting-bugs: see REPORTING BUGS section in \"git help git\"\n\nI don't think it's a good idea to add those \"hint: ...\" and\n\"reporting-bugs: ...\" lines.\n\nI think it's better to do things like the following:\n\n- add `git version -h`\n- add proper documentation for `git version` so that `git help version` works\n- in `git help version` talk about the REPORTING BUGS section in `git help git`\n- add `git version --full` or other such options to also print other\nstuff like the current OS, processor architecture, libc, etc\n- suggest in `git help version` and/or in the REPORTING BUGS section\nin `git help git` that people just copy paste the output of `git\nversion --full` in their bug report\n\n[...]\n\n> I'm still on the fence about whether this is a good idea. At least\n> having custom bug instructions in --build-options sounds like a very\n> nice thing, but it's not obvious to me how people would learn about\n> that option.\n\nYeah indeed.\n\nThanks,\nChristian.\n"},{"id":"313857","messageId":"20170312124725.ogwame2nm72maffy@sigill.intra.peff.net","threadId":"45331","inReplyTo":"CAP8UFD0xCCcmd66ChsfxPBFohekucBx3ib4Ayi+KQOXNZFHMjQ@mail.gmail.com","subject":"Re: [RFC PATCH] help: add optional instructions for reporting bugs","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-03-12T12:47:25Z","receivedAt":"2017-03-12T12:47:35Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Mar 10, 2017 at 10:50:50PM +0100, Christian Couder wrote:\n\n> I don't think it's a good idea to add those \"hint: ...\" and\n> \"reporting-bugs: ...\" lines.\n> \n> I think it's better to do things like the following:\n> \n> - add `git version -h`\n> - add proper documentation for `git version` so that `git help version` works\n> - in `git help version` talk about the REPORTING BUGS section in `git help git`\n> - add `git version --full` or other such options to also print other\n> stuff like the current OS, processor architecture, libc, etc\n> - suggest in `git help version` and/or in the REPORTING BUGS section\n> in `git help git` that people just copy paste the output of `git\n> version --full` in their bug report\n\nI wonder if a \"gitbugs(7)\" manpage would be a good thing. Then \"git help\nbugs\" would find it.\n\nThat still leaves open the question of whether people would find that\ndocumentation, but at least it is less buried than being at the bottom\nof the git(1) page.\n\n-Peff\n"},{"id":"313911","messageId":"CAGZ79kYedz+r-f7HbDiQR6bfUoUK8LL6g42vO=9uGwHtcPkmhg@mail.gmail.com","threadId":"45331","inReplyTo":"20170312124725.ogwame2nm72maffy@sigill.intra.peff.net","subject":"Re: [RFC PATCH] help: add optional instructions for reporting bugs","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-03-13T18:00:40Z","receivedAt":"2017-03-13T18:00:46Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Sun, Mar 12, 2017 at 5:47 AM, Jeff King <peff@peff.net> wrote:\n> On Fri, Mar 10, 2017 at 10:50:50PM +0100, Christian Couder wrote:\n>\n>> I don't think it's a good idea to add those \"hint: ...\" and\n>> \"reporting-bugs: ...\" lines.\n>>\n>> I think it's better to do things like the following:\n>>\n>> - add `git version -h`\n>> - add proper documentation for `git version` so that `git help version` works\n>> - in `git help version` talk about the REPORTING BUGS section in `git help git`\n>> - add `git version --full` or other such options to also print other\n>> stuff like the current OS, processor architecture, libc, etc\n>> - suggest in `git help version` and/or in the REPORTING BUGS section\n>> in `git help git` that people just copy paste the output of `git\n>> version --full` in their bug report\n>\n> I wonder if a \"gitbugs(7)\" manpage would be a good thing. Then \"git help\n> bugs\" would find it.\n>\n> That still leaves open the question of whether people would find that\n> documentation, but at least it is less buried than being at the bottom\n> of the git(1) page.\n\nTo do it right(tm), I assume we have all of the mentioned ways;\nall of them pointing at the same document.\n\nI am on the fence if we want to have a gitbugs and gitversion man page,\nprecisely because I'd expect these instructions to be overwritten\nby downstream users (e.g. all of the 255 linux distributions would put\ntheir own bug tracker there, iff they carry additional patches; so would\nwe internally as we do have a couple of patches on top of next.)\n\nIt might be not as bad for git as it is for the kernel with tainted modules\nsuch that my worries may be unreasonable.\n\nThanks,\nStefan\n"}]}