How to submit a patch

Submitting a patch, getting it reviewed, and committed to the Firefox source tree involves several steps. This article explains how.

Note

We are also providing a Firefox Contributors Quick Reference for contributors.

The process of submission is illustrated by the following diagram, and each step is detailed below:

        graph TD;
    Preparation --> c[Working on a patch];
    c[Working on a patch] --> Testing;
    Testing --> c[Working on a patch];
    Testing --> e[Submit the patch];
    e[Submit the patch] --> d[Getting Reviews]
    d[Getting Reviews] -- Addressing Review comment --> c[Working on a patch];
    d[Getting Reviews] --> h[Push the change];

Preparation

Every change to the code is tracked by a bug report in bugzilla.mozilla.org. Without a bug, code will not be reviewed, and without review, code will not be accepted. To avoid duplication, search for an existing bug about your change, and only if none exists, file a new one. Most communication about code changes take place in the associated code review, so be sure the bug describes the exact problem being solved.

Please verify the bug is for the correct product and component. For more information, ask questions on the newsgroups, or on the #developers room on chat.mozilla.org.

The person working on a bug should be the ‘assignee’ of that bug in Bugzilla. If somebody else is currently the assignee of a bug, email this person to coordinate changes. If the bug is unassigned, leave a message in the bug’s comments, stating that you intend working on it, and suggest that someone with bug-editing privileges assign it to you.

Some teams wait for new contributors to attach their first patch before assigning a bug. This makes it available for other contributors, in case the new contributor is unable to level up to patch creation. By expressing interest in a bug comment, someone from that team should guide you through their process.

Module ownership

All code is supervised by a module owner. This person will be responsible for reviewing and accepting the change. Before writing your code, determine the module owner, verifying your proposed change is considered acceptable. They may want to look over any new user interface (UI review), functions (API review), or testcases for the proposed change.

If module ownership is not clear, ask on the newsgroups or on Matrix. The revision log for the relevant file might also be helpful. For example, see the change log for browser/base/content/browser.js, by clicking the “Git Log” link at the top of Searchfox, or by running git log browser/base/content/browser.js. The corresponding checkin message will contain something like “r=nickname”, identifying active code submissions, and potential code reviewers.

Working on a patch

Changes to the Firefox source code are presented in the form of a patch. A patch is a commit to version control. Firefox and related code is stored in our git repository.

Each patch should represent a single complete change, separating distinct changes into multiple individual patches. If your change results in a large, complex patch, seek if it can be broken into smaller, easy to understand patches representing complete steps, applied on top of each other. This makes it easier to review your changes, leading to quicker reviews, and improved confidence in this review outcome.

Also ensure that your commit message is formatted appropriately. A simple commit message should look like this:

Bug 123456 - Change this thing to work better by doing something. r=reviewers

The text of the message should be what you did to fix the bug, not a description of what the bug was. If it is not obvious why this change is appropriate, then explain why in the commit message. If this does not fit on one line, then leave a blank line and add further lines for more detail and/or reasoning.

The r=reviewers part specifies that reviewers should review the patch and provide feedback before it is integrated into the Firefox codebase. For choosing reviewers, and the full reviewer syntax, please see