All of lore.kernel.org
 help / color / mirror / Atom feed
* [PATCH] git.txt: mention mailing list archive
@ 2018-09-19 16:43 Martin Ågren
  2018-09-20 19:07 ` Junio C Hamano
  0 siblings, 1 reply; 12+ messages in thread
From: Martin Ågren @ 2018-09-19 16:43 UTC (permalink / raw)
  To: git

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


^ permalink raw reply related	[flat|nested] 12+ messages in thread

* Re: [PATCH] git.txt: mention mailing list archive
  2018-09-19 16:43 [PATCH] git.txt: mention mailing list archive Martin Ågren
@ 2018-09-20 19:07 ` Junio C Hamano
  2018-09-26  8:05   ` Martin Ågren
  0 siblings, 1 reply; 12+ messages in thread
From: Junio C Hamano @ 2018-09-20 19:07 UTC (permalink / raw)
  To: Martin Ågren; +Cc: git

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.

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] git.txt: mention mailing list archive
  2018-09-20 19:07 ` Junio C Hamano
@ 2018-09-26  8:05   ` Martin Ågren
  2018-09-26 13:47     ` Taylor Blau
  0 siblings, 1 reply; 12+ messages in thread
From: Martin Ågren @ 2018-09-26  8:05 UTC (permalink / raw)
  To: Junio C Hamano; +Cc: Git Mailing List

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

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] git.txt: mention mailing list archive
  2018-09-26  8:05   ` Martin Ågren
@ 2018-09-26 13:47     ` Taylor Blau
  2018-09-27  5:50       ` [PATCH v2] " Martin Ågren
  0 siblings, 1 reply; 12+ messages in thread
From: Taylor Blau @ 2018-09-26 13:47 UTC (permalink / raw)
  To: Martin Ågren; +Cc: Junio C Hamano, Git Mailing List

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

^ permalink raw reply	[flat|nested] 12+ messages in thread

* [PATCH v2] git.txt: mention mailing list archive
  2018-09-26 13:47     ` Taylor Blau
@ 2018-09-27  5:50       ` Martin Ågren
  2018-09-27  6:37         ` Jonathan Nieder
  0 siblings, 1 reply; 12+ messages in thread
From: Martin Ågren @ 2018-09-27  5:50 UTC (permalink / raw)
  To: git; +Cc: Junio C Hamano, Taylor Blau

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


^ permalink raw reply related	[flat|nested] 12+ messages in thread

* Re: [PATCH v2] git.txt: mention mailing list archive
  2018-09-27  5:50       ` [PATCH v2] " Martin Ågren
@ 2018-09-27  6:37         ` Jonathan Nieder
  2018-09-27 10:35           ` Martin Ågren
  0 siblings, 1 reply; 12+ messages in thread
From: Jonathan Nieder @ 2018-09-27  6:37 UTC (permalink / raw)
  To: Martin Ågren; +Cc: git, Junio C Hamano, Taylor Blau

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

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH v2] git.txt: mention mailing list archive
  2018-09-27  6:37         ` Jonathan Nieder
@ 2018-09-27 10:35           ` Martin Ågren
  2018-09-28 16:56             ` Junio C Hamano
  0 siblings, 1 reply; 12+ messages in thread
From: Martin Ågren @ 2018-09-27 10:35 UTC (permalink / raw)
  To: Jonathan Nieder; +Cc: Git Mailing List, Junio C Hamano, Taylor Blau

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

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH v2] git.txt: mention mailing list archive
  2018-09-27 10:35           ` Martin Ågren
@ 2018-09-28 16:56             ` Junio C Hamano
  2018-09-28 21:20               ` [PATCH] git doc: direct bug reporters to mailing list archive (Re: [PATCH v2] git.txt: mention mailing list archive) Jonathan Nieder
  0 siblings, 1 reply; 12+ messages in thread
From: Junio C Hamano @ 2018-09-28 16:56 UTC (permalink / raw)
  To: Martin Ågren; +Cc: Jonathan Nieder, Git Mailing List, Taylor Blau

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


^ permalink raw reply	[flat|nested] 12+ messages in thread

* [PATCH] git doc: direct bug reporters to mailing list archive (Re: [PATCH v2] git.txt: mention mailing list archive)
  2018-09-28 16:56             ` Junio C Hamano
@ 2018-09-28 21:20               ` Jonathan Nieder
  2018-09-28 22:27                 ` Junio C Hamano
  0 siblings, 1 reply; 12+ messages in thread
From: Jonathan Nieder @ 2018-09-28 21:20 UTC (permalink / raw)
  To: Junio C Hamano; +Cc: Martin Ågren, Git Mailing List, Taylor Blau

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


^ permalink raw reply related	[flat|nested] 12+ messages in thread

* Re: [PATCH] git doc: direct bug reporters to mailing list archive (Re: [PATCH v2] git.txt: mention mailing list archive)
  2018-09-28 21:20               ` [PATCH] git doc: direct bug reporters to mailing list archive (Re: [PATCH v2] git.txt: mention mailing list archive) Jonathan Nieder
@ 2018-09-28 22:27                 ` Junio C Hamano
  2018-09-28 22:29                   ` Jonathan Nieder
  0 siblings, 1 reply; 12+ messages in thread
From: Junio C Hamano @ 2018-09-28 22:27 UTC (permalink / raw)
  To: Jonathan Nieder; +Cc: Martin Ågren, Git Mailing List, Taylor Blau

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.


^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] git doc: direct bug reporters to mailing list archive (Re: [PATCH v2] git.txt: mention mailing list archive)
  2018-09-28 22:27                 ` Junio C Hamano
@ 2018-09-28 22:29                   ` Jonathan Nieder
  2018-09-28 23:09                     ` Jonathan Nieder
  0 siblings, 1 reply; 12+ messages in thread
From: Jonathan Nieder @ 2018-09-28 22:29 UTC (permalink / raw)
  To: Junio C Hamano; +Cc: Martin Ågren, Git Mailing List, Taylor Blau

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

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] git doc: direct bug reporters to mailing list archive (Re: [PATCH v2] git.txt: mention mailing list archive)
  2018-09-28 22:29                   ` Jonathan Nieder
@ 2018-09-28 23:09                     ` Jonathan Nieder
  0 siblings, 0 replies; 12+ messages in thread
From: Jonathan Nieder @ 2018-09-28 23:09 UTC (permalink / raw)
  To: Junio C Hamano; +Cc: Martin Ågren, Git Mailing List, Taylor Blau

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

^ permalink raw reply	[flat|nested] 12+ messages in thread

end of thread, other threads:[~2018-09-28 23:09 UTC | newest]

Thread overview: 12+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2018-09-19 16:43 [PATCH] git.txt: mention mailing list archive Martin Ågren
2018-09-20 19:07 ` Junio C Hamano
2018-09-26  8:05   ` Martin Ågren
2018-09-26 13:47     ` Taylor Blau
2018-09-27  5:50       ` [PATCH v2] " Martin Ågren
2018-09-27  6:37         ` Jonathan Nieder
2018-09-27 10:35           ` Martin Ågren
2018-09-28 16:56             ` Junio C Hamano
2018-09-28 21:20               ` [PATCH] git doc: direct bug reporters to mailing list archive (Re: [PATCH v2] git.txt: mention mailing list archive) Jonathan Nieder
2018-09-28 22:27                 ` Junio C Hamano
2018-09-28 22:29                   ` Jonathan Nieder
2018-09-28 23:09                     ` Jonathan Nieder

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.