Development workflow

The day-to-day workflow for landing changes in mozilla-central (mirrored here as gecko-dev).

Branching

There is no per-feature branching in mozilla-central. All work happens against the tip of central. Long-running work happens on personal user repos, project branches (e.g., try, autoland), or experimental branches that are eventually rebased onto central. The integration branch autoland is where Lando first lands patches; sheriffs merge autoland → central periodically.

A typical change

1. Pull the latest tip.

   hg pull -u    # Mercurial
   # or
   git pull --rebase    # Git

2. Make a feature branch (Git only). In hg you typically commit on top of tip and use bookmarks; with Git you can branch normally.

3. Edit code. Use ./mach build faster for JS/CSS/manifest-only changes; use ./mach build <path> to incrementally rebuild a subdir.

4. Run targeted tests.

   ./mach test path/to/file_to_test
   ./mach mochitest browser/components/.../test_foo.js
   ./mach gtest 'GtestName.*'
   ./mach wpt path/to/wpt/test

5. Lint.

   ./mach lint --outgoing
   ./mach clang-format --outgoing
   ./mach eslint --fix path/to/dir

6. Push to try (optional but encouraged for non-trivial changes).

   ./mach try fuzzy
   # or for a default selector
   ./mach try auto

   Try runs the same tests CI would, but on your unfinished branch. Read the results on Treeherder.

7. Submit to Phabricator.

   moz-phab submit

   moz-phab reads your local commit(s), creates one Phabricator revision per commit, and links them in a stack. Each commit must have a Bug NNNNNN - description first line.

8. Address review. Update commits in place (hg commit --amend or git commit --amend / git rebase -i), then moz-phab submit again.

9. Land. Once reviewers mark the stack Accepted, click "Land" in Phabricator. Lando picks up the request, rebases onto autoland, and lands the patch. The change appears in gecko-dev shortly after.

Build modes

• ./mach build — full build (C++, Rust, JS chrome, packaging).
• ./mach build faster — skip native compilation; rebuild only chrome/JS/CSS. Fast, useful for chrome work.
• ./mach build <subdir> — incremental build of one piece (./mach build dom/ etc.).
• ./mach configure — re-run configure if .mozconfig changed.
• ./mach clobber — rm -rf the objdir.

.mozconfig patterns

A debug build:

ac_add_options --enable-debug
ac_add_options --disable-optimize
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-debug

An optimized build with debug symbols:

ac_add_options --enable-release
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-opt

Many specialized configs ship under build/ (e.g., build/mozconfig.common.override, the artifact build configs).

Artifact builds

For UI/JS-only contributors, you can use prebuilt platform binaries:

ac_add_options --enable-artifact-builds

This downloads a recent Nightly's compiled C++/Rust and only builds the JS/CSS/chrome layer. Drastically faster.

Mach commands cheat sheet

./mach help                  # list everything
./mach search <symbol>       # source search via Searchfox-like local index
./mach run                   # launch the build
./mach run --debugger=lldb   # run under a debugger
./mach try                   # push to try
./mach lint --outgoing       # lint only changed files
./mach python <path>         # run a tree script with PYTHONPATH set up
./mach awsy-test             # AWSY memory tests
./mach raptor                # browser-level perf tests
./mach talos                 # Talos perf
./mach build-backend         # regenerate Makefiles after moz.build edits

Rebasing on a moving tree

mozilla-central moves fast — often hundreds of commits per day. Long-running patches need frequent rebasing. The recommended pattern is a small stack of commits, regularly rebased.

Backouts

If your change regresses tests or performance, sheriffs may back it out. Don't take it personally: it's standard procedure. Backouts get their own commit messages: Backed out changeset XXXXXX (bug NNNNNN) for reason on a CLOSED TREE.

Adding a new file

When you create new source files, you usually must reference them in a moz.build next to them (or its parent). The build will fail if a .cpp is added but not listed in UNIFIED_SOURCES. See tooling and patterns and conventions.