How to contribute to Firefox

The goal of this doc is to have a place where all simple commands are listed from start to end.

This aims to be a simple tutorial for lazy copy and paste.

Each section in this tutorial links to more detailed documentation on the topic.

The whole process is a bit long, it will take time to get things right. If at any point you are stuck, please don’t feel shy to ask on IRC at irc.mozilla.org in #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 should be around 30 minutes (depending on your connection) and the repository should be less than 5GB (~ 20GB after the build).

More information

Install dependencies

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

$ ./mach bootstrap

The default options are recommended. Select “Artifact Mode” if you are not planning to write C++ or Rust code.

More information

Windows dependencies

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

  2. Download and install Visual Studio.

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

$ c:\mozilla-build\

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.

To run it:

$ ./mach run

More information

To write a patch

Make the changes you need in the code base.

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.

To find a reviewer, the easiest way is to do 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, 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.

$ 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, ask the reviewer if they could land the change. They don’t have an easy way to know if a contributor has permission to land it or not.

If the reviewer does not land the patch after a few days, add the Check-in Needed Tags to the review (Edit Revision).

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

More information