Re: [PATCH v2] MyFirstContribution: add avenues for getting help

From: Emily Shaffer <emilyshaffer@google.com>
Date: Nov 18, 2019, 21:45 UTC
Message-ID: <20191118214519.GH22855@google.com>
In-Reply-To: <xmqqv9rk4j1y.fsf@gitster-ct.c.googlers.com>

On Sat, Nov 16, 2019 at 12:05:45PM +0900, Junio C Hamano wrote:

Show 9 quoted lines

> Emily Shaffer <emilyshaffer@google.com> writes:
> 
> > +[[getting-help]]
> > +=== Getting Help
> > +
> > +If you get stuck, you can seek help in the following places.
> 
> Is this list meant to be an exhaustive list of authoritative
> sources?

To the best of my knowledge, as applicable, yeah.

> IOW, are we reasonably sure that some of us would be
> around and give useful help, and that we do not mind readers to
> consider these places "officially endorsed by the project"?

Right. That's my hope. I worry that sending newbies to non-endorsed places for help will lead to them getting incorrect or conflicting help.

> 
> Or is this meant to be a list of reasonably well-known places, but
> may include places where the project does not want to be associated
> with the quality of answers given there?

No.

> I am (implicitly) assuming that it is the former, but I think it is
> better to clarify what this "list of places" is meant to be.

I'll try to fudge the language so that it implies these are official channels for getting help.

> I notice that stack overflow is missing in this list.  Intended?
> Not that I visit there at all nor I would recommend it, but I recall
> seeing questions asked by more than a few people after getting bad
> pieces of advice there.

Hm. SO for getting help contributing to a specific project? That doesn't sound like a likely avenue or a good idea to me, since my understanding is that we don't consider it an "official presence" (some projects do, I guess).

I suppose the kinds of questions I expect to see on StackOverflow include "How do I write a mutex lock in C" or "How do I generate patches with a cover letter", not "I'm stuck on this Git tutorial" or "Would the Git project welcome X change". To me, this doesn't seem like the place to bring it up one way or another.

Show 18 quoted lines

> 
> > +==== https://public-inbox.org/git[git@vger.kernel.org]
> > +
> > +This is the main Git project mailing list where code reviews, version
> > +announcements, design discussions, and more take place. If you fail to receive
> > +help via the channels above, you can ask your question here. The Git list
> > +requires plain-text-only emails and prefers inline and bottom-posting when
> > +replying to mail; you will be CC'd in all replies to you. Optionally, you can
> > +subscribe to the list by sending an email to majordomo@vger.kernel.org with
> > +"subscribe git" in the body.
> 
> Sounds good; I agree with Denton, especially with the mention of
> "you must join" on the other mailing list, that it is a good idea to
> explicitly say that subscription is optional in this entry.
> 
> You can ask questions even if you haven't tried other avenues and
> failed, but this entry makes it sound as if an earlier failure
> elsewhere is a prerequisite for asking for help here.

I envision an exchange sort of like this:

Newbie to git@vger.kernel.org: "I'm having trouble compiling Git and I want to write a patch, I'm getting X error"

Veteran to Newbie, cc git-mentoring, bcc git@vger.kernel.org: "Please build with blah flag and paste console output, plus let us know system information blah blah blah"

I don't mind the idea of pushing folks to ask on the mentoring list first. It's pretty well attended already - just now I count 16 list members, a pretty significant majority of which are project veterans. I have no problem suggesting newbies ask their questions, which others probably had and solved before them, in a space separate from the main mailing list.

Of course if you want to encourage newbies to ask in any of these three venues, weighted equally, I can change the language. But suggesting the main list as a last resort was intentional.

 - Emily