[PATCH] git.txt: mention mailing list archive

[PATCH] git.txt: mention mailing list archive

[Martin Ågren]

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

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 74a9d7edb4..40eaccafb2 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -858,7 +858,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.
+subscribed to the list to send a message there. The mailing list archives
+are available at <https://public-inbox.org/git/>,
+<http://marc.info/?l=git> and other archival sites.
 
 Issues which are security relevant should be disclosed privately to
 the Git Security mailing list <git-security@googlegroups.com>.
-- 
2.19.0.216.g2d3b1c576c

Re: [PATCH] git.txt: mention mailing list archive

[Junio C Hamano]

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

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

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:

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

Re: [PATCH] git.txt: mention mailing list archive

[Martin Ågren]

On Thu, 20 Sep 2018 at 21:07, Junio C Hamano <gitster@pobox.com> wrote:
>
> Martin Ågren <martin.agren@gmail.com> writes:
>
> > 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.
>
> 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

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

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

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

Re: [PATCH] git.txt: mention mailing list archive

[Taylor Blau]

On Wed, Sep 26, 2018 at 10:05:29AM +0200, Martin Ågren wrote:
> On Thu, 20 Sep 2018 at 21:07, Junio C Hamano <gitster@pobox.com> wrote:
> >
> > Martin Ågren <martin.agren@gmail.com> writes:
> >
> > > 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.
> >
> > 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
>
> Your guess is correct, sorry for forcing you to make one.
>
> > 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:
> >
> > >  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.
>
> 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.

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

[PATCH v2] git.txt: mention mailing list archive

[Martin Ågren]

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

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>.
-- 
2.19.0.216.g2d3b1c576c

Re: [PATCH v2] git.txt: mention mailing list archive

[Jonathan Nieder]

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

Re: [PATCH v2] git.txt: mention mailing list archive

[Martin Ågren]

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

Re: [PATCH v2] git.txt: mention mailing list archive

[Junio C Hamano]

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

[PATCH] git doc: direct bug reporters to mailing list archive (Re: [PATCH v2] git.txt: mention mailing list archive)

[Jonathan Nieder]

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:
>> Jonathan Nieder 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.
[...]
> 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 ;-).

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

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 74a9d7edb4..8e6a92e8ba 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -858,7 +858,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.
+subscribed to the list to send a message there.  See the list archive
+at https://public-inbox.org/git for previous bug reports and other
+discussions.
 
 Issues which are security relevant should be disclosed privately to
 the Git Security mailing list <git-security@googlegroups.com>.
-- 
2.19.0.605.g01d371f741

Re: [PATCH] git doc: direct bug reporters to mailing list archive (Re: [PATCH v2] git.txt: mention mailing list archive)

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

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

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.

Re: [PATCH] git doc: direct bug reporters to mailing list archive (Re: [PATCH v2] git.txt: mention mailing list archive)

[Jonathan Nieder]

Junio C Hamano wrote:

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

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

Jonathan

Re: [PATCH] git doc: direct bug reporters to mailing list archive (Re: [PATCH v2] git.txt: mention mailing list archive)

[Jonathan Nieder]

Jonathan Nieder wrote:
> Junio C Hamano wrote:

>> 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.
>
> Sounds good.  Thanks for the heads up, and thanks for the heads up.

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

Sincerely,
Jonathan