Firefox Workflow

This article outlines the recommended workflow for interacting with the Firefox repository (mozilla-unified).

Optimally Configure Mercurial

When you run bootstrap.py or mach bootstrap (if you already have a clone), the bootstrapper will prompt you to run a Mercurial configuration wizard. You should run this wizard and make sure it is happy about your Mercurial state.

You should also run mach bootstrap periodically to ensure Mercurial support files are up-to-date.

Important

The instructions in this article assume the firefoxtree extension is installed. Please activate it when the wizard prompts you to!

Cloning the Repository

Clone the Firefox repository by running:

$ hg clone https://hg.mozilla.org/mozilla-unified firefox
$ cd firefox

Feature Development

So you want to start work on a new Firefox feature? This section is for you.

Start by obtaining the latest code so you aren’t working on old and possibly stale code:

$ hg pull

Then update to the tip of mozilla-central:

$ hg up central

Now, change some stuff. We assume you know how to do this.

Commit your changes:

$ hg commit
<type commit message in editor>

Make more changes and keep committing:

$ hg commit
<another commit message>

Push your changes to Phabricator to initiate code review. See the the Phabricator documentation for more information.

OK. Progress on that feature is blocked waiting on review. It could take a while for that to happen. Let’s start working on something else. We always start by pulling the latest code so our change isn’t out of date before we’ve event started.:

$ hg pull
$ hg up central
<change stuff>
$ hg commit
<change stuff>
$ hg commit

Changing Code After Reviews

A review comes back. Unfortunately review was not granted and you need to make changes. No worries.

We need to update the working directory to the changeset to be modified so we can edit them. How you do this depends on how you are tracking commits. For most workflows, we recommend hg wip (see Workflows for more on this command) to find them. e.g.:

$ hg wip
o   6139:5060abe260e9 gps  vcsreplicator: explicitly record obsolescence markers in pushkey messages
: o   5940:e16f6960cdeb gps  hgmo: update automationrelevance for Mercurial 3.8; r?smacleod
: o   5939:e62f4eb60ef3 gps  mozhg: fix test output for Mercurial 3.8; r?glob
: o   5938:f71be022e59c gps  global: upgrade Mercurial to 3.8.3 (bug 1277714)
:/
o   5937:5a8623230b7a gps  pushlog: convert user and nodes to bytes (bug 1295724); r=smacleod
: o   5717:9c2ca05479e9 gps  hgmo: handle obsolete changesets (bug 1286426); r?glandium

If you want to edit e16f6960cdeb, you would hg up e16f6960cdeb.

Or if you are using bookmarks, you can update directly to the bookmark:

$ hg up my-bookmark
4 files updated, 0 files merged, 0 files removed, 0 files unresolved
(activating bookmark my-bookmark)

Now that your working directory is updated, you can start making changes.

You have several options available to you. If you know the changes are small and won’t conflict if reordered, go ahead and make them now and commit:

<make changes>
$ hg commit
<make more changes>
$ hg commit

Then squash the changesets together:

$ hg histedit

Note

For hg histedit to work without arguments, you’ll need Mercurial 3.7 or newer.

You’ll then need to:

  1. Reorder your fixup changesets to occur immediately after (below) the changesets they will be modifying.
  2. Set the action on these fixup changesets to roll so they are fully absorbed into the changeset that came before.

Alternatively, you can edit changes directly. Again, use hg histedit. But this time, change the action of the changesets you want to modify to edit. Mercurial will print some things and will leave you with a shell. The working directory will have been updated to the state of the commit you are editing. If you run hg status or hg diff you will see that this changesets’s changes are applied to files already. Make your changes to the files then run hg histedit --continue to continue with the history editing.

Note

Advanced users can use the evolve extension <https://bitbucket.org/marmoute/mutable-history> to edit changesets in place.

Once all the changes are made, you’ll want to submit to Phabricator for review once more. Then we’re back to waiting.

Landing Code

You finally get review and can land your changes!

The easiest way to do this is through the use of Lando. You can access Lando through View stack in Lando on the right of your Phabricator review. Clicking this button takes the user to a menu which displays the stack of changesets to land, the history of previous landing attempts and a big green “Preview Landing” button. Clicking this button will allow you to check that the state of the changesets is appropriate for landing, and that there are no landing warnings. If there are landing warnings but you feel the stack can still land despite them, simply check the radio box to acknowledge the risks and proceed as usual.

Lando will attempt to rebase you commits on the head of the autoland repo for you automatically. If it can’t do this (say there was a file merge conflict during the base), an error will (eventually) be displayed in the Lando landing attempt history and you will have to rebase yourself and push the result back to Lando and try the request again.

Note

Only landing to the autoland repo is supported. This is because we will be removing integration repos in the future so the history of mozilla-central isn’t linear and free of merge commits.

If Lando succeeds, Pulsebot will comment in your bug that your changes have landed. Unfortunately, there is not currently any notification that Lando has failed outside of Lando itself, so if the trees are open and your changes have not landed within a few minutes, please check back in MozReview to see if any errors have occurred.

For more detailed information, please reference the Lando user guide.

Manual Reviewer Attribution and Landing

Unable to use Autoland? Follow these instructions.

Update to the tip-most changeset that will land (often a head) after finding the changesets using the technique in the previous section:

$ hg up <SHA-1 or label>

Before landing, we need to rebase our unlanded changesets on top of the latest changeset from an integration branch:

$ hg pull
$ hg rebase -d inbound

If you need to add r= reviewer attribution to the commit message, do that now:

$ hg histedit

Change the action to m for all the changesets and proceed to update commit messages accordingly.

And finally we land:

$ hg push -r . inbound