{"thread":{"id":"49385","subject":"[PATCH] git.txt: mention mailing list archive","startedAt":"2018-09-19T16:44:25Z","lastAt":"2018-09-28T23:09:59Z","messageCount":12,"participants":["Martin Ågren","Junio C Hamano","Taylor Blau","Jonathan Nieder"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"358465","messageId":"6319b34fc808ff6d8948e59f381cc5342b9ef17d.1537375332.git.martin.agren@gmail.com","threadId":"49385","inReplyTo":null,"subject":"[PATCH] git.txt: mention mailing list archive","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2018-09-19T16:43:00Z","receivedAt":"2018-09-19T16:44:25Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"In the \"Reporting Bugs\" section of git(1), we refer to the mailing list,\nbut we do not give any hint about where the archives might be found.\nCopy the text from README.md on this to give potential reporters an\nhonest chance of finding out whether their bug has already been\nreported.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/git.txt | 4 +++-\n 1 file changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 74a9d7edb4..40eaccafb2 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -858,7 +858,9 @@ Reporting Bugs\n \n Report bugs to the Git mailing list where the\n development and maintenance is primarily done. You do not have to be\n-subscribed to the list to send a message there.\n+subscribed to the list to send a message there. The mailing list archives\n+are available at ,\n+ and other archival sites.\n \n Issues which are security relevant should be disclosed privately to\n the Git Security mailing list .\n-- \n2.19.0.216.g2d3b1c576c\n\n"},{"id":"358532","messageId":"xmqqlg7wyol5.fsf@gitster-ct.c.googlers.com","threadId":"49385","inReplyTo":"6319b34fc808ff6d8948e59f381cc5342b9ef17d.1537375332.git.martin.agren@gmail.com","subject":"Re: [PATCH] git.txt: mention mailing list archive","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2018-09-20T19:07:50Z","receivedAt":"2018-09-20T19:07:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Ågren writes:\n\n> In the \"Reporting Bugs\" section of git(1), we refer to the mailing list,\n> but we do not give any hint about where the archives might be found.\n\nAnd why is it a good idea to give that information in Reporting Bugs\nsection? Are we asking the bug reporters to look for similar issues\nin the archive before they send their message? If so, I think that\nwe should be explicit about it, too. Otherwise, the list archive\nlocation would look like an irrelevant noise to those who wanted to\nfind the address to report bugs to.\n\nFor example, we can say something like this:\n\n> Report bugs to the Git mailing list where the\n> development and maintenance is primarily done. You do not have to be\n> subscribed to the list to send a message there.\n +If you want to check to see if the issue has\n +been reported already, the list archive can be found at\n + and other places.\n"},{"id":"358931","messageId":"CAN0heSqA192U-eH8CZJJbKNcimPYxqn6yva6mstsEHnH1-DEGA@mail.gmail.com","threadId":"49385","inReplyTo":"xmqqlg7wyol5.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH] git.txt: mention mailing list archive","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2018-09-26T08:05:29Z","receivedAt":"2018-09-26T08:05:44Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Thu, 20 Sep 2018 at 21:07, Junio C Hamano wrote:\n>\n> Martin Ågren writes:\n>\n> > In the \"Reporting Bugs\" section of git(1), we refer to the mailing list,\n> > but we do not give any hint about where the archives might be found.\n>\n> And why is it a good idea to give that information in Reporting Bugs\n> section? Are we asking the bug reporters to look for similar issues\n> in the archive before they send their message? If so, I think that\n\nYour guess is correct, sorry for forcing you to make one.\n\n> we should be explicit about it, too. Otherwise, the list archive\n> location would look like an irrelevant noise to those who wanted to\n> find the address to report bugs to.\n>\n> For example, we can say something like this:\n>\n> > Report bugs to the Git mailing list where the\n> > development and maintenance is primarily done. You do not have to be\n> > subscribed to the list to send a message there.\n> +If you want to check to see if the issue has\n> +been reported already, the list archive can be found at\n> + and other places.\n\nI think that one reason I avoided spelling out why giving the archive\nlocation was a good thing to do, was that I didn't want to begin a huge\nlist of \"please do this and that\", scaring away potential bug reporters.\nI think your \"If you want to\" solves that problem very nicely. I'll wrap\nthis up later today.\n\nMartin\n"},{"id":"358944","messageId":"20180926134717.GC25697@syl","threadId":"49385","inReplyTo":"CAN0heSqA192U-eH8CZJJbKNcimPYxqn6yva6mstsEHnH1-DEGA@mail.gmail.com","subject":"Re: [PATCH] git.txt: mention mailing list archive","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2018-09-26T13:47:17Z","receivedAt":"2018-09-26T13:47:23Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Wed, Sep 26, 2018 at 10:05:29AM +0200, Martin Ågren wrote:\n> On Thu, 20 Sep 2018 at 21:07, Junio C Hamano wrote:\n> >\n> > Martin Ågren writes:\n> >\n> > > In the \"Reporting Bugs\" section of git(1), we refer to the mailing list,\n> > > but we do not give any hint about where the archives might be found.\n> >\n> > And why is it a good idea to give that information in Reporting Bugs\n> > section? Are we asking the bug reporters to look for similar issues\n> > in the archive before they send their message? If so, I think that\n>\n> Your guess is correct, sorry for forcing you to make one.\n>\n> > we should be explicit about it, too. Otherwise, the list archive\n> > location would look like an irrelevant noise to those who wanted to\n> > find the address to report bugs to.\n> >\n> > For example, we can say something like this:\n> >\n> > > Report bugs to the Git mailing list where the\n> > > development and maintenance is primarily done. You do not have to be\n> > > subscribed to the list to send a message there.\n> > +If you want to check to see if the issue has\n> > +been reported already, the list archive can be found at\n> > + and other places.\n>\n> I think that one reason I avoided spelling out why giving the archive\n> location was a good thing to do, was that I didn't want to begin a huge\n> list of \"please do this and that\", scaring away potential bug reporters.\n> I think your \"If you want to\" solves that problem very nicely. I'll wrap\n> this up later today.\n\nYeah. This is a tricky issue in my mind. On the one hand, getting a\ndeluge of duplicate bug reports is a burden for people who actively\nread and respond to the list. On the other hand, imposing such a burden\non bug reporters is a detriment to Git users, who wouldn't benefit from\nthe fixes that would come with good bug reports.\n\nBut I think that the above is only a problem if bug reporters are\nconsistently ignoring this advice. I don't think they will, since the\nbarrier to entry is already quite high (e.g., sending email is more\nforeign to some than opening a GitHub issue, say).\n\nSo, I think that the suggestion above is a good one, since I believe\nwe'd rather get some bad bug reports than no bug reports at all.\n\nThanks,\nTaylor\n"},{"id":"359030","messageId":"20180927055018.6683-1-martin.agren@gmail.com","threadId":"49385","inReplyTo":"20180926134717.GC25697@syl","subject":"[PATCH v2] git.txt: mention mailing list archive","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2018-09-27T05:50:18Z","receivedAt":"2018-09-27T05:50:36Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"In the \"Reporting Bugs\" section of git(1), we refer to the mailing list,\nbut we do not give any hint about where the archives might be found. Of\ncourse, any web search engine can be used to try to hunt down whether an\nissue is already known. But we can do better by mentioning the archive\nat public-inbox. Make sure to phrase this in a way that avoids raising\nthe bar for reporting.\n\npublic-inbox.org/git/ is usually our preferred archive, since it uses\nmessage ids in its permalinks. But it also has a search function right\nat the top of each page, and searching gives the most recent hits first.\nSearching for some keyword about a bug or regression should pretty\neasily reveal whether it has been recently reported.\n\nHelped-by: Junio C Hamano \nSigned-off-by: Martin Ågren \n---\n Thanks Junio and Taylor for thoughts on this. I agree we do not want\n to scare anyone away. I hope this does the trick.\n\n Documentation/git.txt | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 74a9d7edb4..68393f3235 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -859,6 +859,9 @@ Reporting Bugs\n Report bugs to the Git mailing list where the\n development and maintenance is primarily done. You do not have to be\n subscribed to the list to send a message there.\n+If you want to check to see if the issue has\n+been reported already, the list archive can be found at\n+ and other places.\n \n Issues which are security relevant should be disclosed privately to\n the Git Security mailing list .\n-- \n2.19.0.216.g2d3b1c576c\n\n"},{"id":"359034","messageId":"20180927063735.GC220288@aiede.svl.corp.google.com","threadId":"49385","inReplyTo":"20180927055018.6683-1-martin.agren@gmail.com","subject":"Re: [PATCH v2] git.txt: mention mailing list archive","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2018-09-27T06:37:35Z","receivedAt":"2018-09-27T06:37:41Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi,\n\nMartin Ågren wrote:\n\n> --- a/Documentation/git.txt\n> +++ b/Documentation/git.txt\n> @@ -859,6 +859,9 @@ Reporting Bugs\n> Report bugs to the Git mailing list where the\n> development and maintenance is primarily done. You do not have to be\n> subscribed to the list to send a message there.\n> +If you want to check to see if the issue has\n> +been reported already, the list archive can be found at\n> + and other places.\n\nHm. I think this encourages a behavior that I want to discourage:\nassuming that if a bug has already been reported then there's nothing\nmore for the new user to add.\n\nEspecially because the mailing list is not an issue tracker, this\nwould make it too easy for the project to miss important bugs.\n\nCan this say something more neutral, like\n\n\tSee the list archive at https://public-inbox.org/git/ for\n\tprevious bug reports and other discussions.\n\n? Or if we want to encourage a particular behavior, should we say\nsomething about \"To coordinate with others experiencing the same\nproblem\" or something else that encourages joining in with the\nthread instead of assuming it's taken care of?\n\nThanks,\nJonathan\n"},{"id":"359041","messageId":"CAN0heSpG2jewXuzcZQAeFydW4zanzymSGVqVz2u0myW3Z7Wcrw@mail.gmail.com","threadId":"49385","inReplyTo":"20180927063735.GC220288@aiede.svl.corp.google.com","subject":"Re: [PATCH v2] git.txt: mention mailing list archive","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2018-09-27T10:35:53Z","receivedAt":"2018-09-27T10:36:11Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Hey\n\nOn Thu, 27 Sep 2018 at 08:37, Jonathan Nieder wrote:\n> Martin Ågren wrote:\n>\n> > --- a/Documentation/git.txt\n> > +++ b/Documentation/git.txt\n> > @@ -859,6 +859,9 @@ Reporting Bugs\n> > Report bugs to the Git mailing list where the\n> > development and maintenance is primarily done. You do not have to be\n> > subscribed to the list to send a message there.\n> > +If you want to check to see if the issue has\n> > +been reported already, the list archive can be found at\n> > + and other places.\n>\n> Hm. I think this encourages a behavior that I want to discourage:\n> assuming that if a bug has already been reported then there's nothing\n> more for the new user to add.\n\nIt was my hope that all of these could be inferred from the above text:\n\n\"I'll just drop a mail anyway.\"\n\n\"I wonder if there's a known solution to my issue.\"\n\n\"I wonder if this is known and I can provide some more details compared\nto the original poster.\"\n\n\"Maybe I can find some thread where I can just say '+1'.\"\n\nBut what a language-lawyer reading says is of course a lot less relevant\nthan what a fresh pair of eyes (yours) reads out of the text. Thanks.\n\n> Especially because the mailing list is not an issue tracker, this\n> would make it too easy for the project to miss important bugs.\n>\n> Can this say something more neutral, like\n>\n> See the list archive at https://public-inbox.org/git/ for\n> previous bug reports and other discussions.\n>\n> ?\n\nThis doesn't say \"*Please* see\", but it comes pretty close. Maybe\nsomething like\n\n If you want to, you can see the list archive at, e.g.,\n for bug reports and other discussions.\n\n> Or if we want to encourage a particular behavior, should we say\n> something about \"To coordinate with others experiencing the same\n> problem\" or something else that encourages joining in with the\n> thread instead of assuming it's taken care of?\n\nWe might also conclude that trying to delicately word-smith something\nthat doesn't scare off reports is tricky, and we're better off just\navoiding doing anything which might raise someone's bar for reporting an\nissue. I'm leaning more and more towards \"it's not broken, so don't fix\nit\"...\n\nMartin\n"},{"id":"359219","messageId":"xmqq1s9def2p.fsf@gitster-ct.c.googlers.com","threadId":"49385","inReplyTo":"CAN0heSpG2jewXuzcZQAeFydW4zanzymSGVqVz2u0myW3Z7Wcrw@mail.gmail.com","subject":"Re: [PATCH v2] git.txt: mention mailing list archive","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2018-09-28T16:56:14Z","receivedAt":"2018-09-28T16:56:20Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Ågren writes:\n\n>> Hm. I think this encourages a behavior that I want to discourage:\n>> assuming that if a bug has already been reported then there's nothing\n>> more for the new user to add.\n>\n> It was my hope that all of these could be inferred from the above text:\n>\n> \"I'll just drop a mail anyway.\"\n>\n> \"I wonder if there's a known solution to my issue.\"\n>\n> \"I wonder if this is known and I can provide some more details compared\n> to the original poster.\"\n>\n> \"Maybe I can find some thread where I can just say '+1'.\"\n>\n> But what a language-lawyer reading says is of course a lot less relevant\n> than what a fresh pair of eyes (yours) reads out of the text. Thanks.\n\nI agree with your reading; the most neutral mention \"archive is\nhere\" is not very friendly because the readers do not know what we\nwant out of them being aware of the archive. \"Ah, I may find a\nsolution already there\" was the reaction I wanted to draw by saying\n\"If you want to check if the issue has been reported\", but any of\nthe above is a good reaction.\n\nAnd from that point of view\n\n>> See the list archive at https://public-inbox.org/git/ for\n>> previous bug reports and other discussions.\n\nis just as good, and there is not a big difference between that and\n\n> If you want to, you can see the list archive at, e.g.,\n> for bug reports and other discussions.\n\nthis one, at least to me.\n\n> We might also conclude that trying to delicately word-smith something\n> that doesn't scare off reports is tricky, and we're better off just\n> avoiding doing anything which might raise someone's bar for reporting an\n> issue. I'm leaning more and more towards \"it's not broken, so don't fix\n> it\"...\n\nYup, in short I think any one of the above three is good enough.\nLet's just pick one and move on. Unless somebody sends in an\nimprovement that can be applied readily, by default I'll just \"git\nam\" the one Martin sent, as that is the easiest thing to do ;-).\n\n"},{"id":"359250","messageId":"20180928212049.GD193055@aiede.svl.corp.google.com","threadId":"49385","inReplyTo":"xmqq1s9def2p.fsf@gitster-ct.c.googlers.com","subject":"[PATCH] git doc: direct bug reporters to mailing list archive (Re: [PATCH v2] git.txt: mention mailing list archive)","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2018-09-28T21:20:49Z","receivedAt":"2018-09-28T21:20:55Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Subject: git doc: direct bug reporters to mailing list archive\n\nThe mailing list archive can help a user encountering a bug to tell\nwhether a recent regression has already been reported and whether a\nlongstanding bug has already had some discussion to start their\nthinking.\n\nBased-on-patch-by: Martin Ågren \nImproved-by: Junio C Hamano \nSigned-off-by: Jonathan Nieder \n---\nJunio C Hamano wrote:\n>> Jonathan Nieder wrote:\n\n>>> Hm. I think this encourages a behavior that I want to discourage:\n>>> assuming that if a bug has already been reported then there's nothing\n>>> more for the new user to add.\n[...]\n> Yup, in short I think any one of the above three is good enough.\n> Let's just pick one and move on. Unless somebody sends in an\n> improvement that can be applied readily, by default I'll just \"git\n> am\" the one Martin sent, as that is the easiest thing to do ;-).\n\nI assume this is meant as a nudge, in which case nudge successful. ;-)\n\nMy experience is that bug reporters are very sensitive to hints the\nproject gives about what kind of bugs they want to receive. I'd\nrather make use of that lesson now instead of waiting to relearn it in\nthe wild. Here goes.\n\nThanks, both.\n\n Documentation/git.txt | 4 +++-\n 1 file changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 74a9d7edb4..8e6a92e8ba 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -858,7 +858,9 @@ Reporting Bugs\n \n Report bugs to the Git mailing list where the\n development and maintenance is primarily done. You do not have to be\n-subscribed to the list to send a message there.\n+subscribed to the list to send a message there. See the list archive\n+at https://public-inbox.org/git for previous bug reports and other\n+discussions.\n \n Issues which are security relevant should be disclosed privately to\n the Git Security mailing list .\n-- \n2.19.0.605.g01d371f741\n\n"},{"id":"359261","messageId":"xmqqd0sx9s19.fsf@gitster-ct.c.googlers.com","threadId":"49385","inReplyTo":"20180928212049.GD193055@aiede.svl.corp.google.com","subject":"Re: [PATCH] git doc: direct bug reporters to mailing list archive (Re: [PATCH v2] git.txt: mention mailing list archive)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2018-09-28T22:27:30Z","receivedAt":"2018-09-28T22:27:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> My experience is that bug reporters are very sensitive to hints the\n> project gives about what kind of bugs they want to receive. I'd\n> rather make use of that lesson now instead of waiting to relearn it in\n> the wild. Here goes.\n\nOK. This unfortunately came a bit too late for today's integration\ncycle, so I'll leave this in my inbox and replace what is queued \nwith it later.\n\nUnless there is another one to supersede this proposal comes before\nthat happens, that is.\n\nThanks.\n\n"},{"id":"359262","messageId":"20180928222900.GE193055@aiede.svl.corp.google.com","threadId":"49385","inReplyTo":"xmqqd0sx9s19.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH] git doc: direct bug reporters to mailing list archive (Re: [PATCH v2] git.txt: mention mailing list archive)","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2018-09-28T22:29:00Z","receivedAt":"2018-09-28T22:29:05Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Junio C Hamano wrote:\n\n> OK. This unfortunately came a bit too late for today's integration\n> cycle, so I'll leave this in my inbox and replace what is queued\n> with it later.\n>\n> Unless there is another one to supersede this proposal comes before\n> that happens, that is.\n>\n> Thanks.\n\nSounds good. Thanks for the heads up, and thanks for the heads up.\n\nJonathan\n"},{"id":"359263","messageId":"20180928230953.GA48520@aiede.svl.corp.google.com","threadId":"49385","inReplyTo":"20180928222900.GE193055@aiede.svl.corp.google.com","subject":"Re: [PATCH] git doc: direct bug reporters to mailing list archive (Re: [PATCH v2] git.txt: mention mailing list archive)","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2018-09-28T23:09:53Z","receivedAt":"2018-09-28T23:09:59Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Jonathan Nieder wrote:\n> Junio C Hamano wrote:\n\n>> OK. This unfortunately came a bit too late for today's integration\n>> cycle, so I'll leave this in my inbox and replace what is queued\n>> with it later.\n>>\n>> Unless there is another one to supersede this proposal comes before\n>> that happens, that is.\n>>\n>> Thanks.\n>\n> Sounds good. Thanks for the heads up, and thanks for the heads up.\n\nAhem, what I meant is \"and thanks for the help with writing the\npatch\".\n\nSincerely,\nJonathan\n"}]}