This page is intended to describe what makes up a a good first bug, a good Mentored Bug, and to clarify expectations around what constitutes a good bug-mentoring relationship.

After interviewing several of our engineers about the mentoring experience, it became clear that the most difficult parts of the mentoring experience are knowing when to - and feeling OK about - redirecting contributors who are struggling, out of their depth or dragging on unproductively.

The goal of this document is to help make it clear to new contributors what Mozilla's expectations are as far as readiness and experience are, and what the best practices are towards making a successful contribution, as well as to set out some guidelines for mentors about how to make the mentoring relationship work and how to positively direct a contributor towards a better fit when it isn't.

Good First Bugs

These are tagged as [good first bug] in a bug's Whiteboard field (examples of good first bugs).

The challenge of a "good first bug" is only peripherally about the bug itself. The focus, for a new contributor, should be on getting your development environment set up and learning how to navigate Mozilla's contribution process. There are some excellent documents on MDN to help you get started, and the #introduction IRC channel exists just to help people getting started as contributors.

A good, ahem, good first bug includes an extremely narrow scope, clear hardware and platform requirements, and prompt reviewer followup.

Unfortunately abandoned attempts at first bugs are a common occurrence, and they tie up opportunities for other contributors. Somebody who'd like to be assigned a good-first-bug should have their development environment spun up and a first attempt at a patch submitted for review before they can be properly assigned the bug.

Advice for new developers: Firefox Developer Onboarding.

Narrowly Scoped

An ideal first bug is very narrow in scope, possibly as little as one line, and has the following qualities:

• The problem statement and successful outcome are unambiguous.
• The bug should link to the code to be modified using a DXR link.
• any relevant automated tests should also be identified, as well as instructions for adding any new tests, and
• The bug is not time-critical, blocking on or being blocked by anything else

Clear External Requirements

If any external requirements exist - A particular OS or OS version, hardware, language facility (C++, regular expressions, Urdu) or anything else the contributor should have or know to be successful - that information should be specified in the whiteboard or comments.

Reviewer Followup

We know for a fact that the single biggest influence on contributor retention is response time. Contributors whose contribution is acknowledged within the first two days - even if it is only to thank the contributor and say when it will be reviewed - will generally return to make a second contribution; wait two weeks, and they will not. Please follow up first-bug submissions promptly, and successful reviews with a note about what this contributor might want to work on next.

Good Next Bugs

Marked as [good next bug] on the whiteboard, these are a the next level up, where the challenge of the bug is actually fixing the bug. There are four parts to a well-described Good Next Bug: a willing mentor, a clear initial description of the problem, clear expectations on the part of the both the mentor and contributor, and a cooperative working relationship as the bug is resolved.

Clear Requirements

Above and beyond what normally makes up a good bug description, a Good Next Bug should include:

• A broad description of what an acceptable solution to the bug would look like, in particular including any testing or validation requirements the contributor would need to include for their fix to land.
• If possible, a link to DXR or other relevant repo where the bug resides.
• If possible, links to prior art - similar bugs in Bugzilla, similar tests in the tree.

Diamond Bugs

Marked as [diamond] on the whiteboard, this label doesn't speak to a bug's difficulty, but rather speaks to its importance. Diamond bugs are bugs that have been brought up as important bugs in engineering's various priority-triage processes - for example, front-end engineering's Firefox Priority Backlog meetings - but aren't assigned to an engineer by the end of the triage process.

A diamond bug should always have a mentor associated with it. These bugs are an organizational priority, and their successful completion is important; contributors taking on diamond bugs should do their best to communicate their progress frequently in the bug, and anyone mentoring a diamond bug should do their best to turn around a contributor's questions or feedback promptly.

Experience Required

These bugs are going to be very hard to fix.

Bugs flagged as [experience required] are generally corner-case bugs that live on the ragged edges between two different pieces of technology - JS and C++ on a specific architecture, or a philosophical disagreement between a particular compiler and a particular set of registers on a particular CPU - that require a deep and fine-grained understanding of the technologies involved. We expect these bugs to take a great deal of time, patience and expertise to address.

These bugs must have a mentor associated with them, and while they are not typically going to be high-visibility bugs their completion is of very high value to Mozilla, and we're very interested in having a long-term relationship with contributors who can complete them.

The Contributor's Role

We want the contributor's participation in any mentored bugs to be a good experience that's the start of a long-term relationship.

• For Good Next Bugs, it is generally expected that you've your development environment set up and that you have made some contributions to the Mozilla codebase before. Having successfully completed a Good First Bug is a good indication that you're ready; few if any good-next-bugs will be good starting points for new contributors.
• Regular communication with your mentor is important; your mentor needs confidence that the bug is moving in a good direction, and that you haven't gone into the weeds or lost interest. Please communicate with your mentor on IRC or via email at least once a week.
• While this is at the discretion of mentor, a bug whose contributor goes radio-silent for more than two weeks will generally be deassigned and offered to other contributors.
• Respect the mentor's guidance, particularly with respect to patch submission and review; the successful integration of a mentored contributor's patch is as much a reflection on the mentor's guidance as on the work of the contributor.

The Mentor's Role

We know that the speed and manner in which we reply to new contributors questions is very highly correlated with contributor retention.

• Be judicious in what bugs, as well as what contributors, you agree to mentor. You are not obliged to mentor any particular contributor, but it is a real commitment. Do not hesitate to look up prior work or encourage them to complete a good-first-bug first if you're uncertain.
• Return emailed questions promptly: within 24 hours *at most*. Engagement falloff is measurably worse after 1 day and dramatically worse after three. If possible, establish "office hours" on IRC during which you agree to be available to answer that contributor's questions. You can create a mail filter in your email client to manage mentored bugmail specifically: see here .
• Follow up with contributors who seem to be off track or losing interest. This is an active role, and making sure that a bug is progressing is the mentor's responsibility. That said, not all mentoring relationships will be successful; if you go two weeks without hearing from a contributor on a mentored bug, you should not feel any shame or reluctance before unassigning the bug and putting it back in the common pool.

Following Up

While we have tooling around some community enagement, badges and other recognition tools, please check to make sure:

• That a contributor is recognized for their efforts, even if this is a simple as thanks, and
• that after a successful contribution, that they know what they can do next. By now a mentor should have a good sense of the contributor's capabilities, and the mentor is the best person to suggest what they might want to do next.
• Josh Matthews has created the Mentored Bugs And You presentation.

Thank you

If you have any questions or concerns about the contents of this document or the mentoring process, please contact Mike Hoye