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 https://searchfox.org/firefox-main/source/services/sync

This is just the core JavaScript APIs and logic. Additional Sync code for integration with Firefox lives in https://searchfox.org/firefox-main/source/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 https://searchfox.org/firefox-main/source/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. Read more about Firefox Sync extended logging for fetching successful sync event logfiles.

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 [CloudServices/Sync#Report_Bugs 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. The expected components where bugs will be filed are listed on CloudServices/Sync#Report_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.

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.