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

From: Junio C Hamano <gitster@pobox.com>
To: "Martin Ågren" <martin.agren@gmail.com>
Cc: Jonathan Nieder <jrnieder@gmail.com>,
	Git Mailing List <git@vger.kernel.org>,
	Taylor Blau <me@ttaylorr.com>
Subject: Re: [PATCH v2] git.txt: mention mailing list archive
Date: Fri, 28 Sep 2018 09:56:14 -0700	[thread overview]
Message-ID: <xmqq1s9def2p.fsf@gitster-ct.c.googlers.com> (raw)
In-Reply-To: <CAN0heSpG2jewXuzcZQAeFydW4zanzymSGVqVz2u0myW3Z7Wcrw@mail.gmail.com> ("Martin =?utf-8?Q?=C3=85gren=22's?= message of "Thu, 27 Sep 2018 12:35:53 +0200")

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