[v7] MyFirstContribution: add avenues for getting help
diff mbox series

Message ID 20200124212602.74194-1-emilyshaffer@google.com
State New
Headers show
Series
  • [v7] MyFirstContribution: add avenues for getting help
Related show

Commit Message

Emily Shaffer Jan. 24, 2020, 9:26 p.m. UTC
With https://lore.kernel.org/git/20191114194708.GD60198@google.com/ we
now have a mentoring mailing list, to which we should direct new
contributors who have questions.

Mention #git-devel, which is targeted for Git contributors; asking for
help with getting a first contribution together is on-topic for that
channel. Also mention some of the conventions in case folks are
unfamiliar with IRC.

Because the mentoring list and #git-devel are both a subset of Git
contributors, finally list the main Git list and mention some of the
posting conventions.

Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
---
Took a slightly modified version of Junio's suggestion for the archive
link so the final text reads "The archive of this mailing list is
available to view in a browser" instead of "The archive of this mailing
list is available at archive to view in a browser".

 - Emily

 Documentation/MyFirstContribution.txt | 33 +++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

Comments

SZEDER Gábor Jan. 24, 2020, 9:56 p.m. UTC | #1
On Fri, Jan 24, 2020 at 01:26:02PM -0800, Emily Shaffer wrote:
> With https://lore.kernel.org/git/20191114194708.GD60198@google.com/ we
> now have a mentoring mailing list, to which we should direct new
> contributors who have questions.

Why should a supposedly "open" open source project direct new
contributors to a mailing list that is not openly accessible, and even
reading and searching its archives requires registration?
Junio C Hamano Jan. 24, 2020, 10:05 p.m. UTC | #2
Emily Shaffer <emilyshaffer@google.com> writes:

> Took a slightly modified version of Junio's suggestion for the archive
> link so the final text reads "The archive of this mailing list is
> available to view in a browser" instead of "The archive of this mailing
> list is available at archive to view in a browser".

Looks good.  Thanks.
Junio C Hamano Jan. 24, 2020, 11:44 p.m. UTC | #3
SZEDER Gábor <szeder.dev@gmail.com> writes:

> On Fri, Jan 24, 2020 at 01:26:02PM -0800, Emily Shaffer wrote:
>> With https://lore.kernel.org/git/20191114194708.GD60198@google.com/ we
>> now have a mentoring mailing list, to which we should direct new
>> contributors who have questions.
>
> Why should a supposedly "open" open source project direct new
> contributors to a mailing list that is not openly accessible, and even
> reading and searching its archives requires registration?

Haven't we had that discussion when the mentoring list was launched?

I would not prefer joining a closed list of unknown people over
coming up with a fake name and asking for help in an open list if I
had choice when interacting with an established community as a new
member, but I would understand it if preference of some people are
opposite from mine.  The more important part, from my point of view,
is that we offer choices (the proposed doc update illustrates
three).
SZEDER Gábor Feb. 6, 2020, 1:07 a.m. UTC | #4
On Fri, Jan 24, 2020 at 03:44:40PM -0800, Junio C Hamano wrote:
> SZEDER Gábor <szeder.dev@gmail.com> writes:
> 
> > On Fri, Jan 24, 2020 at 01:26:02PM -0800, Emily Shaffer wrote:
> >> With https://lore.kernel.org/git/20191114194708.GD60198@google.com/ we
> >> now have a mentoring mailing list, to which we should direct new
> >> contributors who have questions.
> >
> > Why should a supposedly "open" open source project direct new
> > contributors to a mailing list that is not openly accessible, and even
> > reading and searching its archives requires registration?
> 
> Haven't we had that discussion when the mentoring list was launched?
> 
> I would not prefer joining a closed list of unknown people over
> coming up with a fake name and asking for help in an open list if I
> had choice when interacting with an established community as a new
> member, but I would understand it if preference of some people are
> opposite from mine.  The more important part, from my point of view,
> is that we offer choices (the proposed doc update illustrates
> three).

I remember a discussion about whether that list and its archive should
be open or closed, and I agree that offering choices is good.
However, since that mentoring list requires registration, we have to
carefully consider how to present it to newcomers.

Openly accessible knowledge is a fundamental value, and it's the
foundation of open source.  Therefore, we definitely should not direct
newcomers to a closed mailing list as the first option, it can only be
a fallback.

The text should list git@vger as the first option, since that's the
only open mailing list we have, it should clearly emphasize that
newcomers are very welcome, and should explicitly encourage them to
post their questions here, no matter how trivial or silly they think
those questions are, we'll be always glad to answer them.

The closed mailing list can be mentioned third as a fallback for those
who would prefer not to end up on public record right away or who have
any technical issues with posting to the main mailing list.
Junio C Hamano Feb. 6, 2020, 4:33 p.m. UTC | #5
SZEDER Gábor <szeder.dev@gmail.com> writes:

> On Fri, Jan 24, 2020 at 03:44:40PM -0800, Junio C Hamano wrote:
>
>> ...  The more important part, from my point of view,
>> is that we offer choices (the proposed doc update illustrates
>> three).
>
> I remember a discussion about whether that list and its archive should
> be open or closed, and I agree that offering choices is good.
> However, since that mentoring list requires registration, we have to
> carefully consider how to present it to newcomers.
>
> Openly accessible knowledge is a fundamental value, and it's the
> foundation of open source.  Therefore, we definitely should not direct
> newcomers to a closed mailing list as the first option, it can only be
> a fallback.

I am not that dogmatic ;-) I would be very unhappy and probably
would not have joined if the main development community was closed,
but I do not think the "knowledge" the "closed mentoring list for
those who are shy" are meant to impart to newbies will be something
that will be so well kept secret that are shared among only those in
the closed list.  I expect the mentoring list to be repeating what
those who graduated "new"-ness consider pretty much common public
knowledge.

Having said that, my reading did hiccup when queuing Emily's text,
in that it listed the mentoring list first, and (more problematic)
the only choice among the three described with a word "great" was
that one.  Also, now I re-read it, the last sentence "You must join
the group to view messages or post", without explaining why it is
set up that way is bound to give a wrong impression, I suppose.  I
presume that the reason why those who wanted to make the mentoring
list closed was because they thought it would be nicer for shysters,
but if that is the case, it probably is better to spell that out.

> The text should list git@vger as the first option, since that's the
> only open mailing list we have, it should clearly emphasize that
> newcomers are very welcome, and should explicitly encourage them to
> post their questions here, no matter how trivial or silly they think
> those questions are, we'll be always glad to answer them.

I have no problem with seeing an expanded invitation to the main
list.  I do not have a strong opinion on the order of three items.

> The closed mailing list can be mentioned third as a fallback for those
> who would prefer not to end up on public record right away or who have
> any technical issues with posting to the main mailing list.

I'll mark the topic on hold (it is in 'next'), and would give the
stakeholders some time to settle the discussion, perhaps with
counter-proposals in an incremental patch form.  Would it be
reasonable to set the deadline around the end of the next week?
Emily Shaffer Feb. 6, 2020, 7:49 p.m. UTC | #6
On Thu, Feb 06, 2020 at 08:33:54AM -0800, Junio C Hamano wrote:
> SZEDER Gábor <szeder.dev@gmail.com> writes:
> 
> > On Fri, Jan 24, 2020 at 03:44:40PM -0800, Junio C Hamano wrote:
> >
> >> ...  The more important part, from my point of view,
> >> is that we offer choices (the proposed doc update illustrates
> >> three).
> >
> > I remember a discussion about whether that list and its archive should
> > be open or closed, and I agree that offering choices is good.
> > However, since that mentoring list requires registration, we have to
> > carefully consider how to present it to newcomers.
> >
> > Openly accessible knowledge is a fundamental value, and it's the
> > foundation of open source.  Therefore, we definitely should not direct
> > newcomers to a closed mailing list as the first option, it can only be
> > a fallback.
> 
> I am not that dogmatic ;-) I would be very unhappy and probably
> would not have joined if the main development community was closed,
> but I do not think the "knowledge" the "closed mentoring list for
> those who are shy" are meant to impart to newbies will be something
> that will be so well kept secret that are shared among only those in
> the closed list.  I expect the mentoring list to be repeating what
> those who graduated "new"-ness consider pretty much common public
> knowledge.
> 
> Having said that, my reading did hiccup when queuing Emily's text,
> in that it listed the mentoring list first, and (more problematic)
> the only choice among the three described with a word "great" was
> that one.  Also, now I re-read it, the last sentence "You must join
> the group to view messages or post", without explaining why it is
> set up that way is bound to give a wrong impression, I suppose.  I
> presume that the reason why those who wanted to make the mentoring
> list closed was because they thought it would be nicer for shysters,
> but if that is the case, it probably is better to spell that out.

Sure. I think I didn't do so in an effort to be brief. I'll think on
this today and send some suggestions here (rather than rerolling).

> 
> > The text should list git@vger as the first option, since that's the
> > only open mailing list we have, it should clearly emphasize that
> > newcomers are very welcome, and should explicitly encourage them to
> > post their questions here, no matter how trivial or silly they think
> > those questions are, we'll be always glad to answer them.
> 
> I have no problem with seeing an expanded invitation to the main
> list.  I do not have a strong opinion on the order of three items.

Me neither, and placing git@vger first does give me an opportunity to
say something like "if you feel worried about asking publicly, this list
is a more private setting" in reference to the mentors list. So that's
an option I could get behind.

> 
> > The closed mailing list can be mentioned third as a fallback for those
> > who would prefer not to end up on public record right away or who have
> > any technical issues with posting to the main mailing list.
> 
> I'll mark the topic on hold (it is in 'next'), and would give the
> stakeholders some time to settle the discussion, perhaps with
> counter-proposals in an incremental patch form.  Would it be
> reasonable to set the deadline around the end of the next week?

Yeah, that is OK for me. I'll try and send another email with some ideas
today or tomorrow.

Thanks for the feedback, Gábor - I appreciate it.

 - Emily
Emily Shaffer Feb. 6, 2020, 10:13 p.m. UTC | #7
On Thu, Feb 06, 2020 at 11:49:29AM -0800, Emily Shaffer wrote:
> On Thu, Feb 06, 2020 at 08:33:54AM -0800, Junio C Hamano wrote:
> > SZEDER Gábor <szeder.dev@gmail.com> writes:
> > 
> > > On Fri, Jan 24, 2020 at 03:44:40PM -0800, Junio C Hamano wrote:
> > >
> > >> ...  The more important part, from my point of view,
> > >> is that we offer choices (the proposed doc update illustrates
> > >> three).
> > >
> > > I remember a discussion about whether that list and its archive should
> > > be open or closed, and I agree that offering choices is good.
> > > However, since that mentoring list requires registration, we have to
> > > carefully consider how to present it to newcomers.
> > >
> > > Openly accessible knowledge is a fundamental value, and it's the
> > > foundation of open source.  Therefore, we definitely should not direct
> > > newcomers to a closed mailing list as the first option, it can only be
> > > a fallback.
> > 
> > I am not that dogmatic ;-) I would be very unhappy and probably
> > would not have joined if the main development community was closed,
> > but I do not think the "knowledge" the "closed mentoring list for
> > those who are shy" are meant to impart to newbies will be something
> > that will be so well kept secret that are shared among only those in
> > the closed list.  I expect the mentoring list to be repeating what
> > those who graduated "new"-ness consider pretty much common public
> > knowledge.
> > 
> > Having said that, my reading did hiccup when queuing Emily's text,
> > in that it listed the mentoring list first, and (more problematic)
> > the only choice among the three described with a word "great" was
> > that one.  Also, now I re-read it, the last sentence "You must join
> > the group to view messages or post", without explaining why it is
> > set up that way is bound to give a wrong impression, I suppose.  I
> > presume that the reason why those who wanted to make the mentoring
> > list closed was because they thought it would be nicer for shysters,
> > but if that is the case, it probably is better to spell that out.
> 
> Sure. I think I didn't do so in an effort to be brief. I'll think on
> this today and send some suggestions here (rather than rerolling).
> 
> > 
> > > The text should list git@vger as the first option, since that's the
> > > only open mailing list we have, it should clearly emphasize that
> > > newcomers are very welcome, and should explicitly encourage them to
> > > post their questions here, no matter how trivial or silly they think
> > > those questions are, we'll be always glad to answer them.
> > 
> > I have no problem with seeing an expanded invitation to the main
> > list.  I do not have a strong opinion on the order of three items.
> 
> Me neither, and placing git@vger first does give me an opportunity to
> say something like "if you feel worried about asking publicly, this list
> is a more private setting" in reference to the mentors list. So that's
> an option I could get behind.

How about something like this?

I was trying to achieve the following goals:

 - Try to remove bias:
   - Don't make git@vger sound like a last-ditch effort or scary place.
   - Don't call git-mentoring@ "great", rather explain why it was
     created
   - Don't imply that all contributors who want to help are present on
     mentoring list, or that all contributors who aren't present on
     mentoring list don't want to help - just indicate that all
     contributors on mentoring list do want to help
 - Explain reasoning around git-mentoring@:
   - avoiding the public eye (and that's why viewing is restricted)
   - targeted membership (people joined because they want to help)

I'm no professional writer, so I expect there's more work to be done.
When we have something we're happy with then I'll send a formal patch.

 - Emily

-- >8 --

---
 Documentation/MyFirstContribution.txt | 29 +++++++++++++++------------
 1 file changed, 16 insertions(+), 13 deletions(-)

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 522c75099d..427274df4d 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -28,11 +28,24 @@ useful additional context:
 
 If you get stuck, you can seek help in the following places.
 
+==== git@vger.kernel.org
+
+This is the main Git project mailing list where code reviews, version
+announcements, design discussions, and more take place. Those interested in
+contributing are welcome to post questions 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. The https://lore.kernel.org/git[archive] of this mailing list is
+available to view in a browser.
+
 ==== https://groups.google.com/forum/#!forum/git-mentoring[git-mentoring@googlegroups.com]
 
-This mailing list is targeted to new contributors and is a great place to post
-questions and receive kind, detailed answers from volunteers on the Git
-project. You must join the group to view messages or post.
+This mailing list is targeted to new contributors and was created as a place to
+post questions and receive answers outside of the public eye of the main list.
+Veteran contributors who are especially interested in helping mentor newcomers
+are present on the list. In order to avoid search indexers, group membership is
+required to view messages; anyone can join and no approval is required.
 
 ==== https://webchat.freenode.net/#git-devel[#git-devel] on Freenode
 
@@ -46,16 +59,6 @@ respond to you. It's better to ask your questions in the channel so that you
 can be answered if you disconnect and so that others can learn from the
 conversation.
 
-==== git@vger.kernel.org
-
-This is the main Git project mailing list where code reviews, version
-announcements, design discussions, and more take place. 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. The https://lore.kernel.org/git[archive] of this
-mailing list is available to view in a browser.
-
 [[getting-started]]
 == Getting Started

Patch
diff mbox series

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 35b9130aa3..522c75099d 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -23,6 +23,39 @@  useful additional context:
 - `Documentation/SubmittingPatches`
 - `Documentation/howto/new-command.txt`
 
+[[getting-help]]
+=== Getting Help
+
+If you get stuck, you can seek help in the following places.
+
+==== https://groups.google.com/forum/#!forum/git-mentoring[git-mentoring@googlegroups.com]
+
+This mailing list is targeted to new contributors and is a great place to post
+questions and receive kind, detailed answers from volunteers on the Git
+project. You must join the group to view messages or post.
+
+==== https://webchat.freenode.net/#git-devel[#git-devel] on Freenode
+
+This IRC channel is for conversations between Git contributors. If someone is
+currently online and knows the answer to your question, you can receive help
+in real time. Otherwise, you can read the
+https://colabti.org/irclogger/irclogger_logs/git-devel[scrollback] to see
+whether someone answered you. IRC does not allow offline private messaging, so
+if you try to private message someone and then log out of IRC, they cannot
+respond to you. It's better to ask your questions in the channel so that you
+can be answered if you disconnect and so that others can learn from the
+conversation.
+
+==== git@vger.kernel.org
+
+This is the main Git project mailing list where code reviews, version
+announcements, design discussions, and more take place. 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. The https://lore.kernel.org/git[archive] of this
+mailing list is available to view in a browser.
+
 [[getting-started]]
 == Getting Started