How to Submit a Patch

  • Revision slug: Developer_Guide/How_to_Submit_a_Patch
  • Revision title: How to Submit a Patch
  • Revision id: 39592
  • Created:
  • Creator: Waldo
  • Is current revision? No
  • Comment lotsa changes, make it complete (not at all concise, yet)

Revision Content

Once you've made a change to the tree, tested it, and created a patch, you can contribute it back to the main source tree. This process consists of three main steps:

  • Attaching the patch to the relevant bug in Bugzilla
  • Getting it reviewed, and finally
  • Getting it checked into the tree

These steps are described in detail in the rest of this article.

Attaching the patch

The first thing you should do to get people looking at your patch is attach it to the relevant bug in Bugzilla. You should first look for an existing bug covering the issue your patch solves and, if you can't find anything, file a new bug.

Make sure to make it clear what exact problem you're solving and, if it's not clear from the patch, how you are solving it. The more clear the issue and the fix is, the more likely it will get looked at.

Once you've found or filed the relevant bug, attach the patch you created earlier to the bug using the "Add an attachment" link. Select the "patch" checkbox so that Bugzilla can show a prettyfied, side-by-side version of it if someone wants to view one (via a "Diff" link next to the patch). If you have the editbugs bit set on your account (see Preferences, then Permissions; it'll be listed if you have it), feel free to check the "take bug" checkbox while you're at it. You can also edit the attachment's attributes after it has been submitted via the "Details" link in the Attachments table in the bug.

The next step is figuring out who the appropriate reviewers for the patch are and asking them to review the patch.

Getting the patch reviewed

Code reviews are Mozilla's way of ensuring code that's not up to snuff doesn't get into the repository. It ensures high code quality: readability, clarity, security, and all that jazz. Currently, most patches have to undergo two reviews: a regular review and a "superreview" (the latter generally tries to look at the big picture of how your patch changes). Reviewers are specific to given areas ("modules") of the codebase, but any super-reviewer may review any patch (although most without knowledge in the area of your patch will usually decline to review and ask you to try someone else). Some areas of the codebase have different review requirements; {{template.Source("js/src")}} requires only a single review, and toolkit/ and browser/ require only a single review. Feel free to ask in the bug when you request the first review if the code you're modifying has special review requirements.

Module owners and peers review patches for code in a module, and they can help you through the process of getting your patch in the tree. The list of modules and people familiar with them is a good place to find someone to review your patch. Another good place to look for reviewers is the CVS log for the files you change. For example, if your patch primarily changes {{template.Source("browser/base/content/browser.js")}}, you can usually choose someone who's recently reviewed patches to the file. To view the logs, visit the file in MXR, view the file, and select the "CVS Log" link at the top of the page. If someone's reviewed a patch, the corresponding checkin will contain something like "r=foobar" or "sr=baz". "foobar" and "baz" are either email addresses or shortened forms of people's names; entering one in the review field will usually (not always) autocomplete and ask the right person for the review. If it doesn't, visit the bug cited in the checkin comment and find the email address of the reviewer there (usually in a comment with text "r=baz" or similar). You can request both review and superreview at once, and if you feel your patch is suitably small, simple, or obvious, you can make both requests to the same person.

Review often isn't a one-time thing; you may need to revise your patch before reviewers are comfortable approving it. This is quite common, especially for your first few patches. Just make the changes they suggest and re-request review, and eventually you'll have a patch that meets their approval.

If a reviewer doesn't respond within a week or so of your making the review request (which is, sadly, not entirely uncommon), you have a few options. Probably the best option is to jump onto #developers on Mozilla's IRC server and ask about it there. The greatest concentration of people is on during weekday afternoons and evenings, PDT, so it's probably best to ask then if you can. You can also ask in the appropriate newsgroup on news.mozilla.org, although this can be a hit-or-miss proposition. Finally, you can try another reviewer and see if you get a faster response.

If you have a question about what to do about a particular bug, don't be afraid to post even a partial patch and ask questions. A question from someone with code is treated very differently than a question without code; demonstrating you've put effort into trying to solve a problem will make others much more likely to put effort into it as well.

Getting the patch checked into the tree

After the attachment for the patch gets an r+sr (or just r+, depending on the module), it's ready for the checkin. If the patch was marked r+ conditional on some simple changes, attach an updated patch, but don't ask for another review. If the person who reviewed the patch trusts you to make the changes correctly, he assumes you can do so and doesn't need to see them for himself.  :-)

Please build the application you're changing with your patch applied, make sure it runs, and passes automatic tests.

Submitting an untested patch might waste the committer's time or even burn the tree. If your patches have a bad track record, people might put off checking in your patches, since it takes more time. It also affects your chances to get access to make your own commits.

Add checkin-needed to the Keywords field of the bug; various people regularly run searches to find these bugs, and your patch will probably be committed within a week or two.

If your patch does not get checked in within a reasonable timeframe, try joining #developers on irc.mozilla.org and asking people there to check it in for you.

After you think you've contributed enough patches, feel free to consider Getting commit access to Mozilla source code.

Revision Source

<p>Once you've made a change to the tree, <a href="en/Mozilla_automated_testing">tested it</a>, and <a href="en/Creating_a_patch">created a patch</a>, you can contribute it back to the main source tree. This process consists of three main steps:
</p>
<ul><li> Attaching the patch to the relevant bug in <a class="external" href="https://bugzilla.mozilla.org/">Bugzilla</a>
</li><li> Getting it reviewed, and finally
</li><li> Getting it checked into the tree
</li></ul>
<p>These steps are described in detail in the rest of this article.
</p>
<h3 name="Attaching_the_patch"> Attaching the patch </h3>
<p>The first thing you should do to get people looking at your patch is attach it to the relevant bug in <a href="en/Bugzilla">Bugzilla</a>. You should first <a class="external" href="http://www.mozilla.org/quality/help/beginning-duplicate-finding.html">look for an existing bug</a> covering the issue your patch solves and, if you can't find anything, <a href="en/Bug_writing_guidelines">file a new bug</a>.
</p><p>Make sure to make it clear what exact problem you're solving and, if it's not clear from the patch, how you are solving it. The more clear the issue and the fix is, the more likely it will get looked at.
</p><p>Once you've found or filed the relevant bug, attach the patch you <a href="en/Creating_a_patch">created earlier</a> to the bug using the "Add an attachment" link. Select the "patch" checkbox so that Bugzilla can show a prettyfied, side-by-side version of it if someone wants to view one (via a "Diff" link next to the patch).  If you have the <code>editbugs</code> bit set on your account (see Preferences, then Permissions; it'll be listed if you have it), feel free to check the "take bug" checkbox while you're at it.  You can also edit the attachment's attributes after it has been submitted via the "Details" link in the Attachments table in the bug.
</p><p>The next step is figuring out who the appropriate reviewers for the patch are and asking them to review the patch.
</p>
<h3 name="Getting_the_patch_reviewed"> Getting the patch reviewed </h3>
<p>Code reviews are Mozilla's way of ensuring code that's not up to snuff doesn't get into the repository.  It ensures high code quality: readability, clarity, security, and all that jazz.  Currently, most patches have to undergo two reviews: a regular review and a "superreview" (the latter generally tries to look at the big picture of how your patch changes).  Reviewers are specific to given areas ("modules") of the codebase, but any <a class="external" href="http://www.mozilla.org/hacking/reviewers.html">super-reviewer</a> may review any patch (although most without knowledge in the area of your patch will usually decline to review and ask you to try someone else).  Some areas of the codebase have different review requirements; {{template.Source("js/src")}} requires only a single review, and <a class="external" href="http://www.mozilla.org/projects/toolkit/review.html">toolkit/</a> and <a class="external" href="http://www.mozilla.org/projects/firefox/review.html">browser/</a> require only a single review.  Feel free to ask in the bug when you request the first review if the code you're modifying has special review requirements.
</p><p>Module owners and peers review patches for code in a module, and they can help you through the process of getting your patch in the tree.  The <a class="external" href="http://www.mozilla.org/owners.html">list of modules and people familiar with them</a> is a good place to find someone to review your patch. Another good place to look for reviewers is the CVS log for the files you change.  For example, if your patch primarily changes {{template.Source("browser/base/content/browser.js")}}, you can usually choose someone who's recently reviewed patches to the file.  To view the logs, visit the file in <a class="external" href="http://mxr.mozilla.org/mozilla/">MXR</a>, view the file, and select the "CVS Log" link at the top of the page.  If someone's reviewed a patch, the corresponding checkin will contain something like "r=foobar" or "sr=baz".  "foobar" and "baz" are either email addresses or shortened forms of people's names; entering one in the review field will usually (not always) autocomplete and ask the right person for the review.  If it doesn't, visit the bug cited in the checkin comment and find the email address of the reviewer there (usually in a comment with text "r=baz" or similar).  You can request both review and superreview at once, and if you feel your patch is suitably small, simple, or obvious, you can make both requests to the same person.
</p><p>Review often isn't a one-time thing; you may need to revise your patch before reviewers are comfortable approving it.  This is quite common, especially for your first few patches.  Just make the changes they suggest and re-request review, and eventually you'll have a patch that meets their approval.
</p><p>If a reviewer doesn't respond within a week or so of your making the review request (which is, sadly, not entirely uncommon), you have a few options.  Probably the best option is to jump onto <a class="external" href="irc://irc.mozilla.org/developers">#developers</a> on Mozilla's IRC server and ask about it there.  The greatest concentration of people is on during weekday afternoons and evenings, PDT, so it's probably best to ask then if you can.  You can also ask in the appropriate newsgroup on <code>news.mozilla.org</code>, although this can be a hit-or-miss proposition.  Finally, you can try another reviewer and see if you get a faster response.
</p><p>If you have a question about what to do about a particular bug, don't be afraid to post even a partial patch and ask questions. A question from someone with code is treated very differently than a question without code; demonstrating you've put effort into trying to solve a problem will make others much more likely to put effort into it as well.
</p>
<h3 name="Getting_the_patch_checked_into_the_tree"> Getting the patch checked into the tree </h3>
<p>After the attachment for the patch gets an r+sr (or just r+, depending on the module), it's ready for the checkin. If the patch was marked r+ conditional on some simple changes, attach an updated patch, but don't ask for another review.  If the person who reviewed the patch trusts you to make the changes correctly, he assumes you can do so and doesn't need to see them for himself.  :-)
</p>
<div class="note">
<p>Please build the application you're changing with your patch applied, make sure it runs, and passes automatic tests.
</p><p>Submitting an untested patch might waste the committer's time or even burn the tree. If your patches have a bad track record, people might put off checking in your patches, since it takes more time. It also affects your chances to get access to make your own commits.
</p>
</div>
<p>Add <a class="external" href="https://bugzilla.mozilla.org/describekeywords.cgi"><code>checkin-needed</code></a> to the Keywords field of the bug; various people regularly run searches to find these bugs, and your patch will probably be committed within a week or two.
</p><p>If your patch does not get checked in within a reasonable timeframe, try joining <a class="external" href="http://irc.mozilla.org/developers">#developers</a> on <a class="external" href="http://irc.mozilla.org/">irc.mozilla.org</a> and asking people there to check it in for you.
</p><p>After you think you've contributed enough patches, feel free to consider <a href="en/Getting_commit_access_to_Mozilla_source_code">Getting commit access to Mozilla source code</a>.
</p>
Revert to this revision