Firefox Contributors’ Quick Reference

Some parts of this process, including cloning and compiling, can take a long time even on modern hardware. If at any point you get stuck, please don’t hesitate to ask at https://chat.mozilla.org in the #introduction channel.

Don’t hesitate to look at the Getting Set Up To Work On The Firefox Codebase for a more detailed tutorial.

Before you start

Important

Before getting started on coding, read our contributor guidelines.

Please register and create your account for

Bugzilla : web-based general-purpose bug tracking system. To register with Phabricator, make sure you enable Two-Factor Authentication (My Profile >> Edit Profile & Preferences >> Two-Factor Authentication) in Bugzilla.

Phabricator: web-based software development collaboration tools, mainly for code review. Please obtain an API Token (Settings >> Conduit API Tokens)

Windows dependencies

  1. You need a supported version of Windows.

  2. Download the MozillaBuild Package. Installation directory should be:

    c:\mozilla-build\
    
  3. Before moving on to the next steps, make sure to fulfill the Windows prerequisites

Note

All the commands of this tutorial must be run in the shell provided with the MozillaBuild Package (start-shell.bat)

More information on building Firefox on Windows

Bootstrap a copy of the Firefox source code

You can download the source code and have Firefox automatically download and install the other dependencies it needs. The below command as per your Operating System, will download a lot of data (years of Firefox history!) then guide you through the interactive setup process.

Downloading can take from 40 minutes to two hours (depending on your connection) and the repository should be less than 5GB (~ 20GB after the build).

The default options are recommended. If you’re not planning to write C++ or Rust code, select Artifact Mode and follow the instructions at the end of the bootstrap for creating a mozconfig file.

To Setup Firefox On Windows

cd c:/
mkdir mozilla-source
cd mozilla-source
wget https://raw.githubusercontent.com/mozilla-firefox/firefox/refs/heads/main/python/mozboot/bin/bootstrap.py

python3 bootstrap.py

More information on building Firefox for Windows.

To Setup Firefox On macOS, Linux, or for Android

curl -L https://raw.githubusercontent.com/mozilla-firefox/firefox/refs/heads/main/python/mozboot/bin/bootstrap.py -O

python3 bootstrap.py

More information on building Firefox for Linux, building Firefox for MacOS and building Firefox for Android.

To set up your editor

Setting up your editor is an important part of the contributing process. Having linting and other features integrated, saves you time and will help with reducing build and reviews cycles.

See our editor page for more information about how to set up your favorite editor.

More advanced git configuration

See the Git tips and tricks page to use a personal fork, and for other useful git configurations.

To build & run

Once the System is bootstrapped, run:

cd firefox
./mach build

which will check for dependencies and start the build. This will take a while; a few minutes to a few hours depending on your hardware.

Note

If you build Firefox often, add ac_add_options \-\-with-ccache=sccache to .mozconfig. sccache will significantly speed up your builds by caching compilation results. The Firefox build system will download sccache automatically.

Note

The default build is a compiled build with optimizations. Check out the mozconfig file documentation to see other build options.

To run it:

./mach run

This command will open your locally built Firefox in a new window.

If you encounter build errors, please reference the more detailed “Building Firefox” document for your operating system (Windows, Linux or macOS) and specifically its “Troubleshooting” section.

To write a patch

Make the changes you need in the codebase. You can look up UI text in Searchfox to find the right file.

Note

If you are unsure of what changes you need to make, or need help from the mentor of the bug, please don’t hesitate to use the needinfo feature (“Request information from”) on Bugzilla to get the attention of your mentor.

After making your changes, visualize your changes to ensure you’re including all the necessary work:

# For files changed/added/removed
git status

# For detailed line changes
git diff

Then commit your changes:

# Git
git commit

The commit message should look like:

Bug xxxx - Short description of your change. r?reviewer

Optionally, a longer description of the change.

Make sure you include the bug number and at least one reviewer (or reviewer group) in this format.

For example, here is an example of a good commit message: “Bug 123456 - Null-check presentation shell so we don’t crash when a button removes itself during its own onclick handler. r=person”

To find a reviewer or a review group, run mach file-info reviewers on the files you modified:

./mach file-info reviewers dom/media/mediasink/AudioSink.cpp

See Getting reviews for the full reviewer syntax and other ways of choosing a reviewer.

To visualize your patch in the repository, run:

# Git
git show

More information on how to work with stack of patches

To make sure the change follows the coding style

To detect coding style violations, use mach lint:

./mach lint path/to/the/file/or/directory/you/changed

# To get the autofix, add --fix:
./mach lint path/to/the/file/or/directory/you/changed --fix

More information

To test a change locally

To run the tests, use mach test with the path. However, it isn’t always easy to parse the results.

./mach test dom/serviceworkers

To run tests based on GTest (C/C++ based unit tests), run:

./mach gtest 'QuotaManager.*'

To test a change remotely

Running all the tests for Firefox takes a very long time and requires multiple operating systems with various configurations. To build Firefox and run its tests on continuous integration servers (CI), multiple options to select tasks are available.

To automatically select the tasks that are most likely to be affected by your changes, run:

./mach try auto

To select tasks manually using a fuzzy search interface, run:

./mach try fuzzy

To rerun the same tasks:

./mach try again

From Treeherder (our continuous integration system), it is also possible to attach new jobs. As every review has a try CI run associated, it makes this work easier. See Profiler symbols for try builds for more information.

Note

This requires level 1 commit access.

You can ask your reviewer to submit the patch for you if you don’t have that level of access.

To request level 1 access, follow the steps in Request commit access level 1.

More information

To submit a patch

To submit a patch for review, we use a tool called moz-phab. To install it, run:

./mach install-moz-phab

Once you want to submit your patches (make sure you use the right commit message), run:

moz-phab

It will publish all the currently applied patches to Phabricator and inform the reviewer.

If you wrote several patches on top of each other:

moz-phab submit <first_revision>::<last_revision>

More information on how to use Phabricator and MozPhab

To update a submitted patch

It is rare that a reviewer will accept the first version of patch. Moreover, as the code review bot might suggest some improvements, changes to your patch may be required.

If your patch is not loaded in your working directory, you first need to re-apply it:

moz-phab patch D<revision_id>

Make your changes in the working folder and run:

# Git
git commit --amend

After amending the patch, you will need to submit it using moz-phab again.

Warning

Don’t use git commit --amend -m.

Phabricator tracks revision by editing the commit message when a revision is created to add a special Differential Revision: <url> line.

When --amend -m is used, that line will be lost, leading to the creation of a new revision when re-submitted, which isn’t the desired outcome.

If you wrote many changes, you can squash or edit commits with the command:

# Git
git rebase -i

The submission step is the same as for the initial patch.

More information on how to work with stack of patches

Retrieve new changes from the repository

To pull changes from the repository, for example when you’re finished with a patch and would like to return to the tip to make a new one, run:

# Git
git pull --rebase

To push a change in the code base

Once the change has been accepted and you’ve fixed any remaining issues the reviewer identified, the reviewer should land the patch.

If the patch has not landed on “autoland” (the integration branch) after a few days, feel free to contact the reviewer and/or @Aryx or @Sylvestre on the #introduction channel.

The landing procedure will automatically close the review and the bug.

More information

Contributing to GeckoView

GeckoView is developed in this repository and follows the same process; see the GeckoView Contributor Guide for the GeckoView-specific steps.

More documentation about contribution

How To Contribute Code To Firefox

Contributing to Mozilla projects

https://mozilla-version-control-tools.readthedocs.io/en/latest/devguide/contributing.html

https://moz-conduit.readthedocs.io/en/latest/phabricator-user.html