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.

Clone the sources

You can use either mercurial or git. Mercurial is the canonical version control system.

$ hg clone https://hg.mozilla.org/mozilla-central/

For git, see the git cinnabar documentation

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

If you have any network connection issues and cannot clone with command, try Mercurial bundles.

More information

Install dependencies (non-Windows)

Firefox provides a mechanism to install all dependencies; in the source tree:

$ ./mach bootstrap

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.

More information for Linux and for MacOS

Windows dependencies

  1. You need 64-bit version of Windows 7 or later.

  2. Download and install Visual Studio Community Edition.

  3. Finally download the MozillaBuild Package. Installation directory should be:

    $ c:\mozilla-build\
    
  4. 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

To build & run

Once all the dependencies have been installed, run:

$ ./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

The default build is a compiled build with optimizations. Check out the mozconfig file documentation to see other build options. If you don’t plan to change C++ or Rust code, an artifact build will be faster.

To run it:

$ ./mach run

More information about Linux / More information about MacOS

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.

Then:

# Mercurial
$ hg commit

# 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.

To find a reviewer or a review group, the easiest way is to run hg log <modified-file> (or git log <modified-file>, if you’re using git) on the relevant files, and look who usually is reviewing the actual changes (ie not reformat, renaming of variables, etc).

To visualize your patch in the repository, run:

# Mercurial
$ hg wip

# Git
$ git show

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

More information

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), two commands are available:

$ ./mach try chooser

To select jobs running a fuzzy search:

$ ./mach try fuzzy

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 Attaching new jobs from a review 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.

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

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.

Run:

# Mercurial
$ hg commit --amend

# Git
$ git commit --amend

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

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

# Mercurial
$ hg histedit

# Git
$ git rebase -i

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

Retrieve new changes from the repository

To pull changes from the repository, run:

# Mercurial
$ hg pull --rebase

# 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, add the Check-in Needed tag to the review (use the Edit Revision option on the top right).

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

More information

Contributing to GeckoView

Note that the GeckoView setup and contribution processes are different from those of Firefox; GeckoView setup and contribution docs live in geckoview.dev.