Mentoring HOWTO

RelEng-Mentoring-HOWTO.mkd

Mentoring HOWTO

Historically release engineering has had a poor track record with contributors.
This has multiple reasons, the three primary ones are:

1. No special effort had been made so far to pull in contributors, contributors were/are unaware that such a team existed and is open to contribution.
2. The nature of release engineering demands utmost security and care, opening up infrastructure and changes to contributors sounds like a bad idea at first.
3. Release engineering at a Mozilla requires a lot of understanding of the infrastructure and existing projects before one can start being productive and typically one also needs access to machines with staging/dev environments for a lot of the more involved work. Both these things have been historically been behind closed walls (machines behind releng firewall/VPN and knowledge either undocumented or in intranet).

This document will try to tackle or at least comment on all these issues in due course. The important thing to not rid that RelEng as a team is trying to change a lot of this going forward. But like any change the transition will be gradual, this doesn't mean there aren't things you can't do right now to improve this situation.

Before we proceed it is important to note that a lot of the things henceforth are generalisations based on personal experience or interaction and conversation with other mentors and contributors. This means it might not be entirely accurate or apply to everyone, but then again it would be hard to write a document that covers all possible cases.

This is a mentoring HOWTO but before one can start mentoring, you actually need to find someone to mentor.

How do we get new contributors?

Build awareness about and interest in release engineering as a team.
There are several ways to do this, but let's go over the primary ones first.

Almost every new contributor to Mozilla will at some point in time go through #introduction. This channel is built especially for the purpose of helping new contributors, if you idle around you'll see at least a dozen people come in asking about how they can contribute to the mozilla project. If they haven't already, they'll almost certainly be redirected to 3 places, the Introduction Wiki Page page, asknot and finally bugsahoy.
It is absolutely imperative that we have release engineering mentioned in all 3 of these places if we as a team want to generate traction and improve visibility. Work has already been done to add release engineering to both bugs ahoy and asknot. The introduction wiki page is a little different in the sense that it is tailored towards core Firefox/Firefox OS hacking and does not mention any of the other teams one may contribute to, for example teams like QA, Automation, Tools, Build and Release can not ideally use that as an introductory page. This is a wider problem across the project and one that we will ignore for now to focus on more pressing concerns.

There are additional ways to get more contributors:

• Keep an eye out for community events such as code sprints or bug squashes, if you come to know of any such events get in touch with the organisers and express your interest to help people out. The drawback here is that these events typically take place out of working hours and/or on weekends so someone actually willing to help out will be going above the beyond the call of duty. (We salute you sir).

• Have/organise a community training/kick start day. Pre announced, pre-planned and well publicised in the community; this can be a 5-6 hour period where a majority of the team helps on-board all incoming people. Ideally there would be two of these days in short succession (consecutive weeks or even in the same week, about 3-5 days apart), for a better smattering of people have the two at times that accommodate different timelines. (If one caters to US/Americas, have another that's Asia friendly). One such setup every quarter might be an achievable goal.

Now assuming that we have contributors' attention we need to address a couple of things.

But before we continue, it might be a good idea to stop and actually look at the ideal "life cycle" of a typical contributor.

Based on experience and interaction with existing contributors one can generalise and breakdown the "life cycle" into 5 stages described below.

I. Absolute Newbie
At this stage the contributor typically knows very little about any project or team. He/she is unfamiliar with the languages and tooling that the team is using and will be typically unsure of what to do and who to ask.

II. Confident beginner
At this stage the contributor has a couple of good first bugs under his or her belt and they are now familiar enough with the tooling to actually get some real work done. They are now looking for slightly meatier bugs.

III. Specialist
At this stage the contributor has worked a lot with a particular project under a specific team, so much so that they know the code base for that particular project and related info almost as well as the author of the project. The knowledge is deep but not very wide.

IV. Master
At this stage the contributor has been around long enough and has worked enough with the team and their various projects that they know almost as much about everything as the full time employees and might even be considered as a "full time employee". (These are the really respected community members).

V. Explorer
This is the stage where the contributor wants to typically spread their wings and branch out to different projects, teams, or even other open source products. This does not necessarily mean they will stop working with their existing team, but contributions are typically sporadic in this phase.

Stages I through IV always happen in order, though the contributor needn't Start at stage I, qualified and talented contributors are sometimes able to go straight to stage II or III.

Stage V can happen simultaneously with any of the other stages and the reasons can wary widely.

Something to note here is that a very small percentage of people in any stage will graduate to the next stage, the rest simply stay at a particular stage or their contributions taper off. The risk of this happening reduces as one progresses through the stages though.

So now that we know a bit more about our hypothetical contributor, let's move on to our next question.

What is a contributor really looking for?

People contribute to F/OSS software for a variety of reasons, but understanding some of them typically helps guide/mentor someone better.

Some of the many possible reasons someone might be willing to contribute is/are:

• They're looking to apply skills/knowledge they learnt in college or via online courses in a real world environment.
• They're a user of F/OSS software and/or your product and would like to give back to the community.
• They enjoy programming as a hobby, and use F/OSS as an outlet or means to purse that hobby.
• The work in your project is closely related to their field of interest or field of research, they're looking to apply new findings they learnt in their field or as part of their research as a proof of concept or as a practical implementation.
• In rare cases, they're out of a paid programming job but need to/would like to keep their skills sharp for when they go back to that line of work.

Regardless of the reason for contribution, a contributor is typically always looking for a few things in any project they decide to contribute to:

• A welcoming and pleasant community. (We have this covered)
• The work they do should be challenging and fulfilling.
• The work they do makes an impact.
• The work they do is valued.
• Working well gradually earns them respect in the community.

If a lot of things on the above list being to go missing then a community begins to lose contributors.

Now that we have a Contributor and a rough understanding of what they want, let's try to figure out the next big question.

How does one deal with contributors?

Helping a Stage I contributor

You need to help them find a bug that matches their interest and skill set. It's also really important that it's a bug that does not require massive amounts of effort to just get started with. Don't throw a newbie into the Lion's den and expect a gladiator to come out on the other side. This is where bugsahoy and well annotated bugs come in, but more on that later.

Stage I contributors are ideally started off with a [good first bug], one that's preferably mentored. The idea behind these isn't to be of great value, these are meant to be simple non-critical fixes/enhancements that help a contributor get a feel of the team's work-flow and tooling.

A contributor will need plenty of help with the work-flow and they'll need to be guided through the patch generation-submission-feedback-review-checkin cycle. Hopefully a master doc/wiki page can cover these points and will reduce the mentor's work to simply pointing the contributor to this doc instead of having to re-explain this to each new contributor.

A contributor in Stage I will require the maximum amount of effort. Contributors come from very different backgrounds and will almost always be lacking in one or more of the tools that the team uses and/or works with. These tools might be the language itself, it could be version control, Linux/unix, issue tracking software, IRC etc.

A mentor will typically have to sit down with a lot of patience and be willing to invest time to help the contributor get comfortable with the tooling initially. After this initial barrier is over though, things get a lot easier. The first bug is the hardest. Throwing in useful "trade" tips about new tools or how to use their tools more efficiently always helps.

The rule of thumb is that the later a contributor is in the "life-cycle" the less effort you need to put in as a mentor.

After the bug has been found and work has begun, the single most important thing might be to actually keep the contributor engaged.

Keeping a contributor engaged boils down to being responsive.

Contributors in stage I & II will have a lot of questions. If possible answer them right away. But sometimes you can't because there's other more pressing concerns. Now you'll want to answer these questions, but being responsive is not about answering questions immediately, it's about giving the contributor some response.

There are multiple ways to do this. If a question is thrown at you and you can't answer it immediately let the person in question know you're busy/in a mtg/in the middle of something and will be available to help them out, the important thing is to not make them feel like no one's paying attention. Alternatively you can ask them to mail their questions to you, or punt the question to someone else on the team (assuming there's mutual understanding of course)

Related side note: People new to IRC often confuse IRC with instant messaging and thus expect similar response times, typically they won't stick around for longer than ~5 minutes for a response. A response by anyone on the channel (even a simple "hi thanks for your interest, someone will answer your question shortly, hang in there") extends the stay time by a lot. Contributors gradually learn that response times on IRC are differnt from those on IM.

The first bug is important from a lot of perspectives to both parties involved.

For the contributor it's a first impression of how the team works, how inviting the existing community is and they'll figure out whether the like the work that the team does,

For the team, a properly picked good first bug will be a good indicator of the dedication, passion and skill level of a new contributor, the team can then use these parameters to decide if they want to invest their time in such a contributor. Typically if someone comes in and they check any two of those three boxes then you'll probably know within the first couple of bugs at most.

Helping a Stage II contributor

A stage II contributor is comfortable with the tooling and work-flow to some extent and has a couple of good first bugs under his/her belt. He/she will thus be looking for "meatier" bugs. You won't have to make as much effort while helping out a stage II contributor, after you've helped the contributor find a bug (shouldn't be a good first bug, they've graduated) you basically need to is answer bug related questions or queries and then provide feedback and review on the patches and not much more.

Helping a Stage III contributor A stage III contributor is one who's worked enough to know the ropes by now and can now pickup and work on bugs on his/her own. They'll only need the occasional feedback and review. A stage III contributor can also help bootstrap other Stage I and Stage II contributors, especially for his/her specialization.

Helping a Stage IV contributor A stage IV contributor is extremely rare and a new contributor can take years to transform into a stage IV contributor if it happens at all. A stage IV contributor typically knows enough to not need any help and can in fact at times be of great help to existing employees, the occasional review and feedback is all that's needed but one can always rely on a stage IV contributor for a review and feedback on their own patch.

What are your responsibilities as a mentor?

As a mentor you're the first point of contact for a contributor. There are 4 major responsibilities over and above your responsibilities as a RelEng-er (we come to these soon):

1. Help the contributor find the right bug for them.

   Ask them about their skill-set and their interests and help to access the difficulty of a bug they might have chosen and incase the bug isn't a good fit, don't be afraid to let them know about the possible difficulties upfront and suggest alternatives. You're a lot more likely to know what a bug would involve than the incoming contributor.

2. Answer questions and queries.

   You're the first point of contact and you're likely to be thrown a lot of questions, try to answer them to the best of your abilities. If you can't, feel free to point them to someone who can, or to a doc that might help. The fact that you're around to answer questions doesn't mean a contributor gets to slack off by asking lmgtfy-type questions and expecting answers in IRC. it's always fair game to ask them to google or to lookup the documentation or the wiki. Please do remember the part about being responsive from above though. It's still fairly important.

3. Provide timely feedback, needinfo and reviews.

   Long waiting times on feedback/reviews after slaving away for days to upload a patch can be fairly off-putting for a contributor. A 2-3 day response time on feedbacks/reviews is really important. If for whatever reason you really can't review the patch or give feedback within that time, fallback to being responsive by telling the contributor in a comment on the bug that you won't be able to get to it till date X or punt to someone else if they're free.

4. Follow up after a successful bug.

   After a contributor has submitted a patch and it's been reviewed and checked in, as a mentor you can help keep the contributor engaged by asking them if they wish to work on another bug, in other words redirect to step 1. from above. If you have no bugs at the moment you can mentor, you can always perform a "hand-off" by introducing the contributor to someone else on the team who does have a bunch of bugs the contributor can work on.

What are your responsibilities as a member of RelEng? (Regardless of whether you're mentoring or not)

1. Triaging and annotating bugs.

   This is the single most important contribution you can make to help the opening up RelEng. Contributors come in everyday and ask for work and currently we have nothing to give them because we don't have a whole lot of well annotated and triaged bugs.

   RelEng is a little bad at how it handles bug filing at the moment. Bugs are filed with a brief description and assume a lot of internal knowledge to actually grok what the bug is about. For a new contributor this is fairly intimidating. The fact that a project is typically always tracked as a single massive bug doesn't help either.

   As a RelEng-er what you can do is triage the bugs you filed, or the bugs filed in the component you own and do the following:

   1. Identify and mark Easy bugs as good first bug, with the [good first bug] whiteboard tag.
   2. Add a meaningful description that explains what the bug is to a layperson. Ideally add details of how to reproduce the bug, what th expected output should be, what the current output/behaviour is. Adding a link to the relevant repo/file/line that causes the problem is also highly advised.
   3. Add yourself as mentor to the bug if you think you'll have bandwidth to mentor if and when someone comes along. This obviously not compulsory, but it always helps.

   The importance of identifying, annotating and describing your bugs cannot be overstated. It's the single most important thing you can do to help the effort to make releng more open at this point. Well annotated bugs are the fuel that is needed to actually have the contributor cycle run, if there are no bugs someone without lots of prior knowledge can tackle then even the most dedicated contributor is likely to fail.

   This may sound like a lot of time consuming work, but one doesn't have to go in and file/annotate all their bugs in one go, annotating about 5-10 bugs a week (this should take no more than an hour a week) is a fairly good start and it will keep the list of fixable contributor bugs nice and healthy.

   Another small change yet recommend when filing bugs is to file a bunch of small bugs tied to each other using the dependncy marking system in bugzilla instead of filing one massive-per-proect bug that stays open for months on an end. This (hopefully) makes work more managable and let's a contributor get in on the action of a new project by possibly working on one of the smaller/easier bug fixes without breaking or disrupting the workflow of the project.

2. "Default to Open"

   Move all possible converstations, discussions, knowledge and decision making rationale out into the public. Use #releng instead of #mozbuild, use a public mailing list instead of release@moco, move knowledge to and dump new knowledge into wiki.m.o instead of intranet.

Open Questions:

1. How do we make RelEng even more open and easy to contribute to?
2. How do we solve the problem of giving access to infrastructure and dev machines required to hack on so many of the RelEng projects?
3. How do we make contributions to and by RelEng more visible? (Pete was thinking of using Mozilla Badges this is not a bad idea. An Honour roll/Leader board of RelEng contributors is another suggestion)

---

Feedback and brutal critique welcome and well appreciated.