Paul Biggar's blog archive

Helping new contributors - Part 2 - Mentoring

Getting into the Mozilla code base can be pretty hard. Even experienced developers may need help finding a good place to start.

Up until now, we’ve been using the good first bug whiteboard annotation in bugzilla to tell contributors where to start, and we’re trying to iterate on the model based on the experience of Mozilla developers. After some discussion, we’ve started using a new whiteboard annotation, which we hope will come to replace the existing good first bug annotation:

[[email protected]]

Add this to a bug—with your own bugzilla ID of course—to tell a newcomer that you will mentor them through this bug. By having existing contributors take personal responsibility for new contributors, we hope to make it easier to shepherd them through the difficult early stages of contribution.

When marking a bug as mentored, you should also add a comment, telling newcomers where to start, where to look for docs, etc. Avoid jargon if possible; newcomers are going to have trouble understanding things we take for granted. Some community members have already started creating mentored bugs, which I hope demonstrate what we’re going for [1].

When a contributor starts working on a bug you mentor, be as friendly and outgoing as possible. Email them privately to thank them, and tell them to contact you with any problems they have or any jargon they may not understand. Your aim should be to help them with anything that they wouldn’t know about Mozilla, which is quite a lot.

Find a reviewer for them, push their patches to tryserver if necessary, and ping their reviewer if required [2]. Get them onto IRC so they can get help when you’re not around, and point them at the right documentation. If they produce a good patch, apply for level 1 access on their behalf, and vouch for them. After review, push their patch, and comment to mention what a great job they’re doing. If you can, suggest a slightly harder a bug for them to do next.

As well as adding new mentored bugs, it’s useful to triage old good first bugs. If they’re still useful, convert them to mentored bugs. If they’re out-of-date, close them, and optionally start a new bug with updated information.

What makes a good mentored bug?

Mentored bugs are basically the same as good first bugs, but with a mentor. That means we can use the same criteria as before:


The best possible first bug, from a procedural point of view, would be a typo fix [3]. It would be trivial to fix, but would serve to teach you bugzilla, build firefox, meet other developers, format your patch correctly, ask for review, and so on. These procedural issues are what makes contribution difficult, and a perfect first bug would just guide people through these steps.


Bugs which depend on other bugs, or which span many modules, are probably not great first bugs. The contributor will be unused to Mozilla’s practices, and having to split work across multiple trees, figure out super-review, etc, are not going to encourage them to stay.


You should be able to guide the contributor down the right track, which means you should understand the bug yourself. Similarly, the bug should have a good start and finish - it should be obvious when the bug is fixed. Bugs which contain a reduced test case are perfect for this; intermittent oranges are not. In general, you should know how you’d approach it, and you should add that as a comment: how to reproduce the problem, the file and function to fix, how you’ll recognize the required fix, etc.


The last thing you want is for the contributor to pour hours into fixing a bug, only for it to be nixed by the reviewer or module owner. You should be 100% certain that fixing the bug is desired, and that there won’t be any dissent at a later date. We don’t want newcomers leaving because their time was wasted.

Although we say “easy” above, we can also mentor bugs that would serve as good second and third bugs. Second and third bugs can add a little more difficultly and discovery. They should still be conceptually easy, but hold a small challenge for someone who doesn’t know the codebase. They’ve jumped through the hoops, now reel them in with something slightly meaty and interesting [4].

What kinds of bugs are useful to mentor?

In general, they should be bugs you’d like to see fixed, but ones that aren’t so important that you’ll do them yourself. Good examples are:

Small bugs you don’t have time for:

For example, the JS team wants to integrate our two testing frameworks, but we probably won’t do it ourselves.

Bugs you’ve started, but won’t finish:

I’ve started a few bugs that I ran out of time to finish, but I still want them to get done. In those cases, I attached what I had done and marked them as mentored. These bugs are particularly good since they are really close to being finished, and the trajectory a new contributor needs to take is unambiguous.

Broken windows:

Mozilla is an old project, and has accrued many broken windows - things which are an incredibly low priority to fix, but make the place look ugly and run-down. These are ideal starting points, especially if they only involved deleting code. Beware that this can lead to scope creep: a new contributor recently removed WinCE support from SpiderMonkey, which had to be split into 5 separate bugs requiring 5 separate reviewers. This can scare new contributors off [5].


Refactorings are a very good way to learn a code-base, though they won’t always be good first bugs (perhaps second or third bugs). It’s always great when a contributor can add something of beauty, instead of a hacky fix.

Local optimizations:

If you have a single function that could be optimized, that makes for a very self-contained bug. The new contributor can write a micro-benchmark and optimize it, and really see the results of their work.

Next steps

We’re currently directing newcomers to an introductory page, where we link to mentored bugs, and encourage newcomers to pick a bug they’d like to work on. It seems that giving newcomers bugs directly is far more effective than leaving them to find one they like, so we’d like to move to that if possible. Unfortunately, we don’t have enough mentored bugs, or a wide enough variety of them, to make this work just yet.

This is particularly true of non-C++ bugs. We have lots of newcomers who don’t know C++, or who barely know it. We currently have an introductory page for people who don’t know C++, but we’d like to do a lot better here. If you work on a aspect of Mozilla that doesn’t use C++, whether it’s RelEng, a website, or even a small tool, we’d love feedback on how to help newcomers work with you.

Speaking of feedback, we want lots of it. Mentored bugs are new to Mozilla, though they’ve been used in other projects before. We’d love to hear your experiences with them, here and elsewhere, to see if we’re really improving things. Our contact details are in the first post, and we’ll keep the mentors page updated as we go.

[1] We’re in early stages here, so feedback welcome.

[2] We don’t want new contributors to be frustrated by having to wait days or weeks for a review. “John here is a new contributor, would you be able to prioritize this review?” works wonders; even if it doesn’t speed up the review, it makes the contributor feel special. I’ll get into this more in a later installment.

[3] However, since it wouldn’t give the contributor a warm fuzzy feeling, probably best not to file these.

[4] For example, here’s a bug I wrote specifically for a new contributor. It’s a challenging bug, but is self-contained and well-understood.

[5] Though it didn’t in this case, cause he is awesome. He actually then went on to delete WinCE from the whole damn tree!