patchgit.txt: mention mailing list archive

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. Copy the text from README.md on this to give potential reporters an honest chance of finding out whether their bug has already been reported.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/git.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

Martin Ågren <martin.agren@gmail.com> writes:

And why is it a good idea to give that information in Reporting Bugs section? Are we asking the bug reporters to look for similar issues in the archive before they send their message? If so, I think that we should be explicit about it, too. Otherwise, the list archive location would look like an irrelevant noise to those who wanted to find the address to report bugs to.

For example, we can say something like this:

  +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.

On Thu, 20 Sep 2018 at 21:07, Junio C Hamano <gitster@pobox.com> wrote:

Your guess is correct, sorry for forcing you to make one.

I think that one reason I avoided spelling out why giving the archive location was a good thing to do, was that I didn't want to begin a huge list of "please do this and that", scaring away potential bug reporters. I think your "If you want to" solves that problem very nicely. I'll wrap this up later today.

Martin

On Wed, Sep 26, 2018 at 10:05:29AM +0200, Martin Ågren wrote:

Yeah. This is a tricky issue in my mind. On the one hand, getting a deluge of duplicate bug reports is a burden for people who actively read and respond to the list. On the other hand, imposing such a burden on bug reporters is a detriment to Git users, who wouldn't benefit from the fixes that would come with good bug reports.

But I think that the above is only a problem if bug reporters are consistently ignoring this advice. I don't think they will, since the barrier to entry is already quite high (e.g., sending email is more foreign to some than opening a GitHub issue, say).

So, I think that the suggestion above is a good one, since I believe we'd rather get some bad bug reports than no bug reports at all.

Thanks, Taylor

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(+)

Hi,

Martin Ågren wrote:

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:

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.

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.

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:

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

is just as good, and there is not a big difference between that and

this one, at least to me.

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 ;-).

Subject: git doc: direct bug reporters to mailing list archive

The mailing list archive can help a user encountering a bug to tell whether a recent regression has already been reported and whether a longstanding bug has already had some discussion to start their thinking.

Based-on-patch-by: Martin Ågren <martin.agren@gmail.com>
Improved-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
Junio C Hamano wrote:

[...]

I assume this is meant as a nudge, in which case nudge successful. ;-)

My experience is that bug reporters are very sensitive to hints the project gives about what kind of bugs they want to receive. I'd rather make use of that lesson now instead of waiting to relearn it in the wild. Here goes.

Thanks, both.

 Documentation/git.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

Jonathan Nieder <jrnieder@gmail.com> writes:

OK. This unfortunately came a bit too late for today's integration cycle, so I'll leave this in my inbox and replace what is queued with it later.

Unless there is another one to supersede this proposal comes before that happens, that is.

Thanks.

Junio C Hamano wrote:

Sounds good.  Thanks for the heads up, and thanks for the heads up.

Jonathan

Jonathan Nieder wrote:

Ahem, what I meant is "and thanks for the help with writing the patch".

Sincerely, Jonathan