Services/Sync/Getting Started

Hacking

Source Code

Once you have a copy of the Mozilla source tree (read below for how to obtain a copy), you can find the core Sync source code in:

/services/sync/

You can view this online at https://searchfox.org/firefox-main/source/

This is just the core JavaScript APIs and logic. Additional Sync code for integration with Firefox lives in:

/browser/base/content

Look for files with sync in their name. Files here define the integration between Firefox and Sync. This includes all the Sync UI.

Additionally, Firefox Accounts specific code lives in

/services/fxaccounts

Debugging Sync

If you are debugging Sync in your browser, the first thing you want to do is crank up the logging. In about:config, set the following preferences:

# Enable logging to Error Console
services.sync.log.appender.console Trace

# Enable logging to STDOUT
services.sync.log.appender.dump Trace

# Log full sync logs on sync success (typically they are only saved on failure)
services.sync.log.appender.file.logOnSuccess true

# Enable trace logging for engines
services.sync.log.logger.engine Trace

# (optional) Enable trace logging for all of sync (this is very verbose and will include all request bodies)
services.sync.log.logger Trace

Once you've updated those settings, restart Firefox for them to take effect.

If you are logging to STDOUT, you may want to set the environment variable MOZ_QUIET to silence a lot of spew from other parts of Firefox:

export MOZ_QUIET=1

You can view full sync logs by opening about:sync-log in Firefox.

Building Sync

You probably should build using an artifact build, as described here.

After setting this up, you'll do `mach build` to perform a build, `mach run` to run Firefox, and `mach xpcshell-test /services/sync/tests/unit` to run the sync unit test suite. There's also a separate end-to-end test suite, TPS, which is documented here. (For most changes it's sufficient that you run the unit tests.)

Depending on your OS, most changes will not require a rebuild to take effect, only restarting and rerunning via `mach run`.

Using Bugzilla

Every code change starts out as a bug in Bugzilla where the general approach can be discussed. The bug should eventually be assigned to somebody who will upload one or more patches for review. Code can only be reviewed by module owners and their peers; see code review policy for more information. If the review has been granted and all review comments have been addressed, the patches may be checked into mozilla-central.

You probably also want to get up to speed on Bugzilla if you're not already.

• A good start is to go watch Jonath's "Bugzilla for Humans" video.
• Sync bugs are found in different places depending on which part of the system they affect. For the service side (syncstorage or tokenserver), bugs will be in [1]. For the client side, you can find a list of components here.
• Don't forget to add a Bugzilla ID shortcut string to your Bugzilla account preferences. The current standard practice is to append "<whitespace>[:irc_nick]" to your Real Name field.
• You also want to watch the components relevant to your work so you automatically get emails for all bug changes in those components. One way to do this is to add the default QA contact for each component to the list of users you are watching in Bugzilla.
  • Open the list of products and components
  • In another tab go to your Bugzilla email preferences
  • At the bottom of the page under the User Watching section there is an input form that takes a comma separated list of email addresses
  • If you're working on server side components, you will want to add at least:
    • core-server@services.bugs
    • sync-server@services.bugs
• A useful Firefox add-on that makes life in Bugzilla a bit easier is Bugzilla Tweaks. Highly recommended!

Using Git

Various projects exist as Git repositories instead of Mercurial repositories. Even when projects are officially hosted in Mercurial, Git mirrors are maintained. The mozilla-central mirror is available at https://github.com/mozilla/gecko-dev, however we recommend that you use https://github.com/glandium/git-cinnabar/wiki/Mozilla:-A-git-workflow-for-Gecko-development to set up a local git repository that tracks mozilla central. If you already have a gecko-dev clone, you can use this guide to configure it to push to hg using git-cinnabar.

Configuring Git

If this is your first time using Git, you'll need for perform some one-time configuration:

# Configure your global name and email. These will be used for commit info.
$ git config --global user.name "John Doe"
$ git config --global user.email "johndoe@mozilla.com"

# Enable color output for all commands
$ git config --global color.branch auto
$ git config --global color.diff auto
$ git config --global color.grep auto
$ git config --global color.interactive auto
$ git config --global color.status auto
$ git config --global color.ui auto

# Highlight whitespace
$ git config --global core.whitespace "trailing-space,space-before-tab,tab-in-indent"

# Define your editor for commits, other tools
$ git config --global core.editor vim

If you find you have a slow git prompt, you may find the instructions here beneficial as well.

Testing

Writing xpcshell-based unit testing. Sync tests are located at /services/sync/tests/unit

TPS Tests

Miscellany

• You also want to grab a Nightly build of Firefox. Everybody in the company should be running a nightly build: it's a great way to find bugs before the code goes out to the general public. If you want to run against different profiles (which is useful for development), you will be interested in two extra command flags: "-P and --no-remote"
  • -P forces the Profile Picker (You probably want to have more than one.)
  • --no-remote allows multiple versions to run on one machine at the same time.