GOP-PROP 2: mentors and Frogs - probably decision

[Graham Percival]

Not much change from the initial one.
http://lilypond.org/~graham/gop/gop_2.html


** Proposal summary

Many new contributors expect more help than they’re getting. We
should either:

   1. give them more help, or
   2. tell them up-front that they won’t be getting help. Think of
a roller-coaster entrance sign, but instead of saying "you must be
THIS tall to ride", we say "you must be THIS smart" or "you must
be THIS much of an independent programmer to contribute". 

I would prefer to get people more help, but more than anything
else I want to make sure that volunteers have a realistic
expectation of how things will work.

I have discovered a truly marvelous proposal for giving them more
help, which this summary is too narrow to contain.


** Rationale

I’ve had emails from 5-10 contributors/developers in the past year
who were concerned/upset/disheartened about not getting feedback.
It’s not just one or two people being whiny. We have a serious
problem.

That said, as far as I’m concerned, the problem is
miscommunication. As the GPL says, releasing source code does not
imply any warrantee. Existing developers are under no obligation
to do anything, not even to reply to questions about the source
code. Somebody spending 10 hours trying to figure out how the
website build system does not obligate me to spend 2 minutes
replying to his emails. (I personally will respond to such emails,
but that is a matter of indivdiual choice – and if I was under any
obligation to reply, I would instead quit the LilyPond project
immediately)


** Trade offs and finding a balance

Even if a significant number of developers were willing to spend a
significant amount of time mentoring new contributors, it’s not
clear that this would be a net gain to the project. If a new
contributor requires 2 hours of mentoring, does work that would
take his mentor 10 minutes to do, then leaves, then it’s a net
loss to the project.

It’s impossible to give any kind of accurate estimate about how
much development effort we "lost" to mentoring and
programs+policies to make things easier for new contributors. Most
developers don’t have a strict policy of X hours for lilypond per
week, so if they spent Y hours helping beginners, we can’t assume
that they would have spent Y hours fixing bugs instead. In
addition, there’s a fairly weak correlation between "time spent
programming" and "quality of code".

My vague estimate, based on reading lilypond-devel and looking at
git commit messages for the past year, is that we lost 5-15% of
developer effort towards helping new contributors, and we gained
about 20-30% from contributors. In other words, I think that our
current amount of new contributor-friendliness provided a benefit
to the project, but not an overwhelming one.

For the record, I do not dispute that most (over 50%) of the "most
active" (no precise definition here) developers required little or
no mentoring. That is a general rule true of almost all
open-source projects, and LilyPond does not break that profile.
But this does not imply that we should give no help at all; there
are still many people who could become extremely valuable
developers if they had a bit of mentoring to begin.

More background reading on this topic:

http://percival-music.ca/blog/2010-08-01-sustainable-development.html
http://blogs.gnome.org/bolsh/2011/05/31/effective-mentoring-programs/
http://percival-music.ca/blog/2011-06-11-lilypond-2.14.html


** Proposal details

I’m not suggesting that we give new contributors as much help as
possible; we need to find a good balance. Let’s make a three-stage
process:

   1. Frog ("apprentice"): any newcomer is directed to the frog
mailing list, and the Frog Meister will "mentor" all frogs. The
Frog Meister is not reponsible for any technical skills or patch
reviewing. He is expected to explain how to use lilydev and upload
patches to Rietveld, but other than that he is responsible for
"pastoral care" – does the contributor feel involved, does he have
somebody to talk to, are there enough people reviewing the
contributor’s patches, etc.

      Carl has agreed that he is "too square" to undertake such a
role, so I’d be looking for a volunteer for this position. The
Frog Meister does not to have git push ability.

   2. "Journeyman": after some amount of work (2-3 months? 5-10
patches?), a developer will offer to mentor a Frog. Exact details
are left up to each frog-developer pair, but the basic idea is
that the frog should have shown that he is serious enough to
warrant such attention+time from a skilled developer.

      Potentially we could even have a "journeyman" officially
mentoring another "journeyman", but at the moment I think it would
be enough to encourage them to still participate on the frog
mailing list.

   3. Developer ("master"): somebody with git push ability. You
know how things work (or not); your patches will hopefully get
added to the patches list and go through countdowns, etc.

      If it took you a lot of pain to reach this stage, then
hopefully you’ll consider mentoring one or two people.

I think the guidelines for mentors are still good, but I’m not
certain if we’ve been following them. For that matter, I’m not
certain how many actual contributor-mentor pairs we have – we
certainly don’t have a tradition of these – so maybe the whole
question is premature.

http://lilypond.org/doc/v2.15/Documentation/contributor/mentors


** Implementation notes

Graham should keep track of all contributor-mentor pairs, and
maybe even have weekly discussions with mentors about how their
contributors are doing. (see the gnome.org/blosh/ blog post)

No technical implementation needed; we already have the frogs
mailing list, and if IRC or voice chat would be useful, such
infrastructure already exists.


** Contributor responsibilities

(this section is copied from the CG, but additional small changes
may be made)

   1. Ask your mentor which sections of the CG you should read.
   2. If you get stuck for longer than 10 minutes, ask your
mentor. They might not be able to help you with all problems, but
we find that new contributors often get stuck with something that
could be solved/explained with 2 or 3 sentences from a mentor.
   3. If you have been working on a task much longer than was
originally estimated, stop and ask your mentor. There may have
been a miscommunication, or there may be some time-saving tips
that could vastly simply your task.
   4. Send patches to your mentor for initial comments.
   5. Inform your mentor if you’re going to be away for a month,
or if you leave entirely. Contributing to lilypond isn’t for
everybody; just let your mentor know so that we can reassign that
work to somebody else.
   6. Inform your mentor if you’re willing to do more work – we
always have way more work than we have helpers available. We try
to avoid overwhelming new contributors, so you’ll be given less
work than we think you can handle. 

Mentor responsibilities

(this section is copied from the CG, but additional small changes
may be made)

   1. Respond to questions from your contributor(s) promptly, even
if the response is just “sorry, I don’t know” or “sorry, I’m very
busy for the next 3 days; I’ll get back to you then”. Make sure
they feel valued.
   2. Inform your contributor(s) about the expected turnaround for
your emails – do you work on lilypond every day, or every weekend,
or what? Also, if you’ll be unavailable for longer than usual
(say, if you normally reply within 24 hours, but you’ll be at a
conference for a week), let your contributors know. Again, make
sure they feel valued, and that your silence (if they ask a
question during that period) isn’t their fault.
   3. Inform your contributor(s) if they need to do anything
unusual for the builds, such as doing a “make clean / doc-clean”
or switching git branches (not expected, but just in case...)
   4. You don’t need to be able to completely approve patches.
Make sure the patch meets whatever you know of the guidelines (for
doc style, code indentation, whatever), and then send it on to the
frog list or -devel for more comments. If you feel confident about
the patch, you can push it directly (this is mainly intended for
docs and translations; code patches should almost always go to
-devel before being pushed).
   5. Keep track of patches from your contributor. Either upload
them to Rietveld yourself, or help+encourage them to upload the
patches themselves. When a patch is on Rietveld, it’s your
responbility to get comments for it, and to add a link to the
patch to the google tracker. (tag it “patch-new”, or
“patch-review” if you feel very confident in it)
   6. Encourage your contributor to review patches, particularly
your own! It doesn’t matter if they’re not familiar with C++ /
scheme / build system / doc stuff – simply going through the
process is valuable. Besides, anybody can find a typo!
   7. Contact your contributor at least once a week. The goal is
just to get a conversation started – there’s nothing wrong with
simply copy&pasting this into an email:
        

      Hey there,

      How are things going?  If you sent a patch and got a review,
      do you know what you need to fix?  If you sent a patch but
      have no reviews yet, do you know when you will get reviews?
      If you are working on a patch, what step(s) are you working
      on?


** Other notes

"Geographic proximity helps big time". Talking to somebody
face-to-face can help tremendously. Failing that, sharing the same
language and/or country and/or time zone (or sleep cycle, for
those who refuse to submit to the tyranny of the sun ;) can help.

I could imagine that some contributor-mentor pairs could meet up
in a cafe in Paris once a month, or have a weekly 30-minute phone
call (or skype session), or at least have weekly "how are you
doing" emails. 


Cheers,
- Graham