| Message ID | 20180927055018.6683-1-martin.agren@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v2] git.txt: mention mailing list archive | expand |
Hi, Martin Ågren wrote: > --- a/Documentation/git.txt > +++ b/Documentation/git.txt > @@ -859,6 +859,9 @@ Reporting Bugs > Report bugs to the Git mailing list <git@vger.kernel.org> where the > development and maintenance is primarily done. You do not have to be > subscribed to the list to send a message there. > +If you want to check to see if the issue has > +been reported already, the list archive can be found at > +<https://public-inbox.org/git/> and other places. Hm. I think this encourages a behavior that I want to discourage: assuming that if a bug has already been reported then there's nothing more for the new user to add. Especially because the mailing list is not an issue tracker, this would make it too easy for the project to miss important bugs. Can this say something more neutral, like See the list archive at https://public-inbox.org/git/ for previous bug reports and other discussions. ? Or if we want to encourage a particular behavior, should we say something about "To coordinate with others experiencing the same problem" or something else that encourages joining in with the thread instead of assuming it's taken care of? Thanks, Jonathan
Hey On Thu, 27 Sep 2018 at 08:37, Jonathan Nieder <jrnieder@gmail.com> wrote: > Martin Ågren wrote: > > > --- a/Documentation/git.txt > > +++ b/Documentation/git.txt > > @@ -859,6 +859,9 @@ Reporting Bugs > > Report bugs to the Git mailing list <git@vger.kernel.org> where the > > development and maintenance is primarily done. You do not have to be > > subscribed to the list to send a message there. > > +If you want to check to see if the issue has > > +been reported already, the list archive can be found at > > +<https://public-inbox.org/git/> and other places. > > Hm. I think this encourages a behavior that I want to discourage: > assuming that if a bug has already been reported then there's nothing > more for the new user to add. It was my hope that all of these could be inferred from the above text: "I'll just drop a mail anyway." "I wonder if there's a known solution to my issue." "I wonder if this is known and I can provide some more details compared to the original poster." "Maybe I can find some thread where I can just say '+1'." But what a language-lawyer reading says is of course a lot less relevant than what a fresh pair of eyes (yours) reads out of the text. Thanks. > Especially because the mailing list is not an issue tracker, this > would make it too easy for the project to miss important bugs. > > Can this say something more neutral, like > > See the list archive at https://public-inbox.org/git/ for > previous bug reports and other discussions. > > ? This doesn't say "*Please* see", but it comes pretty close. Maybe something like If you want to, you can see the list archive at, e.g., <https://public-inbox.org/git/> for bug reports and other discussions. > Or if we want to encourage a particular behavior, should we say > something about "To coordinate with others experiencing the same > problem" or something else that encourages joining in with the > thread instead of assuming it's taken care of? We might also conclude that trying to delicately word-smith something that doesn't scare off reports is tricky, and we're better off just avoiding doing anything which might raise someone's bar for reporting an issue. I'm leaning more and more towards "it's not broken, so don't fix it"... Martin
Martin Ågren <martin.agren@gmail.com> writes: >> Hm. I think this encourages a behavior that I want to discourage: >> assuming that if a bug has already been reported then there's nothing >> more for the new user to add. > > It was my hope that all of these could be inferred from the above text: > > "I'll just drop a mail anyway." > > "I wonder if there's a known solution to my issue." > > "I wonder if this is known and I can provide some more details compared > to the original poster." > > "Maybe I can find some thread where I can just say '+1'." > > But what a language-lawyer reading says is of course a lot less relevant > than what a fresh pair of eyes (yours) reads out of the text. Thanks. I agree with your reading; the most neutral mention "archive is here" is not very friendly because the readers do not know what we want out of them being aware of the archive. "Ah, I may find a solution already there" was the reaction I wanted to draw by saying "If you want to check if the issue has been reported", but any of the above is a good reaction. And from that point of view >> See the list archive at https://public-inbox.org/git/ for >> previous bug reports and other discussions. is just as good, and there is not a big difference between that and > If you want to, you can see the list archive at, e.g., > <https://public-inbox.org/git/> for bug reports and other discussions. this one, at least to me. > We might also conclude that trying to delicately word-smith something > that doesn't scare off reports is tricky, and we're better off just > avoiding doing anything which might raise someone's bar for reporting an > issue. I'm leaning more and more towards "it's not broken, so don't fix > it"... Yup, in short I think any one of the above three is good enough. Let's just pick one and move on. Unless somebody sends in an improvement that can be applied readily, by default I'll just "git am" the one Martin sent, as that is the easiest thing to do ;-).
diff --git a/Documentation/git.txt b/Documentation/git.txt index 74a9d7edb4..68393f3235 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -859,6 +859,9 @@ Reporting Bugs Report bugs to the Git mailing list <git@vger.kernel.org> where the development and maintenance is primarily done. You do not have to be subscribed to the list to send a message there. +If you want to check to see if the issue has +been reported already, the list archive can be found at +<https://public-inbox.org/git/> and other places. Issues which are security relevant should be disclosed privately to the Git Security mailing list <git-security@googlegroups.com>.
In the "Reporting Bugs" section of git(1), we refer to the mailing list, but we do not give any hint about where the archives might be found. Of course, any web search engine can be used to try to hunt down whether an issue is already known. But we can do better by mentioning the archive at public-inbox. Make sure to phrase this in a way that avoids raising the bar for reporting. public-inbox.org/git/ is usually our preferred archive, since it uses message ids in its permalinks. But it also has a search function right at the top of each page, and searching gives the most recent hits first. Searching for some keyword about a bug or regression should pretty easily reveal whether it has been recently reported. Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Martin Ågren <martin.agren@gmail.com> --- Thanks Junio and Taylor for thoughts on this. I agree we do not want to scare anyone away. I hope this does the trick. Documentation/git.txt | 3 +++ 1 file changed, 3 insertions(+)