This is a guide to contributing to the Firefox Developer Tools. At a high level, the workflow for a contributor looks like this:
- Get set up
- Get the Firefox source code
- Get a build environment, so you can build Firefox
- Fix a bug
- Find a bug to fix
- Fix it, and write some tests
- Get your fix reviewed
- Check in your fix
- Make a patch that's ready to check in
- Run integration tests
- Ask a release engineer to check in your patch
This guide:
- assumes that:
- You know Git but not Mercurial, and are not interested in learning Mercurial at the moment
- You are potentially interested in making more than one contribution, so are willing to invest a little time in getting set up to run integration tests
- does not cover the design and implementation of the DevTools code itself. For this, you're better off asking for help in the #devtools IRC channel or in the bug you are working on.
- describes only one possible workflow. There are various different techniques people use for different parts of this workflow. The workflow describes here may not be the most efficient, but is a relatively simple and stable one. You can read about additional workflows in the Alternative techniques section of this document.
Mozilla source control: Mercurial and Git
Some of the complexities in working with Mozilla source code derive from the fact that Mozilla uses Mercurial as a version control system, not Git. If you know Mercurial, this is fine: but most people coming to Mozilla are familiar with Git but not Mercurial. What's more, most people are not interested in learning a new version control system just to make a few contributions to Firefox.
There is a Git mirror of the Firefox source code at https://github.com/mozilla/gecko-dev. It's kept up to date, and you can use it to build Firefox and work on your contribution, all the way through to getting final approval for your patch. However, the Git mirror is read-only: you can't push changes back to Firefox using only Git. Changes in Firefox must be committed to the Mercurial repository.
Usually, for your first patch, your mentor will take care of committing the patch for you, and you don't need to worry about Mercurial at all. However, if you want to become a regular contributor, you will need to be able to run integration tests (called pushing to try in Mozilla jargon), and to do this, you'll need to be able to push to a Mercurial repository.
In this guide we'll describe a setup which enables you to do this while still being able to use Git for your development, although there are other such setups.
Getting set up
Getting the Firefox source
Clone the GitHub mirror from https://github.com/mozilla/gecko-dev. This might take a while.
git clone https://github.com/mozilla/gecko-dev.git
The DevTools team uses the inbound branch for development, so check that branch out:
cd gecko-dev git checkout inbound
Build prerequisites
The source code includes a tool called mach, that you'll use to build, run, and test Firefox. It also has a bootstrap command that sets up our build environment, so run that now:
./mach bootstrap
This could also take a while, as it installs all your prerequisites.
Getting set up with Mercurial
Next, clone the Mercurial Firefox repository into a parallel directory:
cd .. hg clone http://hg.mozilla.org/integration/mozilla-inbound
(mach bootstrap should already have installed Mercurial for you.)
Next, install the Mozilla git tools in another parallel directory:
git clone https://github.com/mozilla/moz-git-toolsMake sure the scripts in this repository are executable by your shell by adding this directory to your $PATH in your .bash_profile.
At this point you should have a directory structure like:
dev /fx-team /gecko-dev /moz-git-tools
Building Firefox
To build Firefox, navigate to the gecko-dev directory and execute ./mach build. This will take a while:
cd gecko-dev ./mach build
Once you've built everything, you can build just the DevTools using:
./mach build devtools/*
This is much faster.
Note that whenever you pull the latest changes from fx-team into your local repository, you may need to "clobber". A "clobber" is similar to a "make clean". You'll know you need to clobber when you get a big error message telling you to do a clobber build after you tried to do an incremental build. To do a clobber build, enter these commands:
./mach clobber ./mach build
Running Firefox
To run the Firefox you built:
./mach run
Or:
./mach run -P my-profile
This will instruct mach to run Firefox with the profile named "my-profile" (you can name the profile whatever you want). A profile is where all customizations of the basic Firefox installation are kept, including browsing history, tweaked settings, add-ons, and bookmarks. If the profile you specify does not already exist, it will be created.
Running tests
To run tests, use mach test, passing it a single test file or a directory containing test files:
./mach test path/to/test
Fixing a bug
We use Bugzilla for bug tracking, so you'll need to sign up there.
Finding a bug
If you don't already know what you want to work on, check out the list of good first bugs and mentored bugs at the firefox-dev.tools site (alternatively, you can find these lists on Bugzilla: good-first, mentored). This list of all open developer tools bugs might have other items you'd find interesting to work on.
Asking questions
While working on the bug, feel free to ask for help. If you don't know who to contact, this page should help you. Don't hesitate to ask to be mentored even on bugs that don't have a mentor assigned yet.
If you add a comment to your bug and need a response from someone, you can set the "Needs more information" (commonly abbreviated to NI) check box underneath the comment box, and add their email address:
This will flag the bug for their attention.
Asking for feedback
If you have a patch that's not yet ready for a proper review, but want feedback on a possible approach to solving a problem, you can attach your work-in-progress patch and ask for feedback.
To attach a patch, click the link in the bug labeled "Add an attachment". This opens a new page in which you can attach the patch, as well as ask for feedback or ask for review:
Asking for review
Once you think you are ready for review, create a patch. At this point the patch does not need any particular formatting, as long as it applies cleanly to the fx-team branch. For example, you could just use the output of git diff fx-team. If you have trouble finding the right reviewer, you can refer to this page.
However, it must apply cleanly to the fx-team branch, so rebase your working branch before you create the patch, and fix up any conflicts.
You can ask for a review without including tests. But you will have to write tests, and get them reviewed as well, before you can check in your contribution.
Dealing with review comments
If the reviewer finds things that need to be fixed they will note them in the bug, and mark the review rejected (r-). Don't feel discouraged about this: it very common for even experienced Firefox developers to have their patches rejected.
Create a new patch that addresses the comments, attach it, and ask for review again. When you attach the patch, check the box that says that this new patch obsoletes the old one.
When your patch is approved, the reviewer will mark it r+.
It's possible that the reviewer will have some additional comments called "nits": these are things that should be fixed, but don't require another review round.
If you've got an r+ on a patch, but then fix the nits, or for some other reason have to regenerate the patch, then you can "carry over the r+": this means that you can mark it as "r+" yourself, when you attach the new patch.
Checking in
So you've now implemented a feature, written tests, and it's all been reviewed. The final step is to run integration tests and, if they pass, ask for checkin.
Creating a patch to check in
Rebasing
First you'll need to rebase your changes into a single commit, with a commit message in the following format:
git commit -m "Bug 12345 - Summary of bug. r=<name of reviewer>" .Setting name and email
Check that your name and email address are set correctly in your .gitconfig, like this:
[user]
name = My Name
email = me@my-domain.com
Set up and run hgp
In the .git/config for your gecko-dev clone, add this line:
[alias]
hgp = "show --binary --find-renames --format=\"# HG changeset patch%n# User %an <%ae>%n%B\" -U8"This adds a command to git called hgp, which will take the last commit you made and convert it into an Mercurial-style patch.
Next, run:
git hgp HEAD > Bug12345.patchThis will generate a patch in Mercurial format. Attach this patch to the bug.
Pushing to try
Mozilla runs integration tests using servers called "try servers". To use a try server, you apply your patch, add a specially formatted commit message which tells the server which platforms to test, and push it to a specific Mercurial repository. The try servers then run integration tests as directed by the commit message, and you can see the results online.
First, you need commit access level 1 to push to the try server. File a bug asking for commit access level 1, attach the SSH public key you will be using (you can use the same one you use for GitHub, if you like), and ask your mentor to vouch for you.
Next, make sure your Mercurial repository (fx-team in Getting set up) is up to date. Make sure that your Git repository (gecko-dev in Getting set up) is in sync with it, with the addition of your patch.
Next, navigate to your gecko-dev directory and push to try with a command like this:
git push-to-try ../fx-team -b do -p linux,linux64,macosx64,win32 -u xpcshell,mochitests -t noneThe long string of parameters here tells the server which platforms to use, and which tests to run. The set quoted above is a common set for DevTools changes, but your mentor can help you choose a different set if necessary.
If this is successful, the output from the command will give you a URL you can use to check on the progress of your build/test run.
Interpreting try results/retriggering
A complete try build/test run takes several hours. The page that shows you the results looks something like this:
Each row represents a platform, and each linked item in the row represents a test suite (for example, dt1, dt2, dt3 are DevTools test suites). Ideally you want all of these to be green. Red is a build error, orange is a test failure, and purple is an infrastructure failure.
Quite often, there are test failures, and these show up as orange. If you click the linked item, you'll see a detailed view about the test failure in the pane at the bottom:
Test failures are often associated with known intermittent bugs in Bugzilla, and if this is the case, that fact is noted in the detailed view. The screenshot above is showing us that this test failure is associated with bug 1177730.
If you have test or build failures, you'll need to determine whether or not they are caused by your patch. If they seem to be unconnected with the changes you've made, and are associated with a known intermittent, there's a good chance that they are not caused by your patch. One way to help determine this is to retrigger just that job: you can do this by clicking the "reload" icon:
Discuss any test failures with your mentor and decide whether it's OK to ask for checkin, or whether there are problems in your patch that need to be addressed.
Setting the checkin-needed keyword
If you've decided to go ahead with checkin, add a comment to your bug containing a link to the try run. If there are any test failures that you think are not caused by your patch, explain why you think that. Then add the "checkin-needed" keyword to the bug. To do this, just click in the "Keywords" text box in the bug, type "checkin-needed" and press Enter.
Within a few hours, a release engineer will check your patch into the tree.
What's next?
Once your patch is checked in, there will be another round of build and test. If that's successful the patch will be merged into the mozilla-central branch of the Firefox code. Then, in the next day or so, your patch will appear in Nightly builds of Firefox, and will then appear in the next release of the Developer Edition.
Getting help
The two best ways to get help are:
- Asking questions in the bug
- Asking questions in the #devtools channel on IRC. If you haven't used IRC before, see this guide to using IRC at Mozilla.
Alternative techniques
The workflow described above is not the only possible workflow for Firefox Devtools development. There are alternative techniques for many of the steps, and in many cases these are more efficient and advanced, although they are also more experimental. You can customize the basic workflow by replacing pieces of it with some of these techniques.
- Contribute on Nightly: this describes a new technique which enables you to modify and reload the devtools code without having to build Firefox or even to set up a build environment.
- git-cinnabar: this tool provides a bridge between Git and Mercurial, enabling you to push changes to Mercurial without needing to clone any Mercurial repositories.