Services/Sync/Getting Started

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 services-central, which is the Mercurial repository used for Services client work.

On rare occasions it will make more sense to land work on mozilla-central instead — for example, if a change needs to propagate upstream before the regular merge from services-central to mozilla-central. This might involve additional procedures (e.g., you need to request approval in addition to review.)

For server code written in Python, Tarek has provided a useful tool called flake8 which does Python style checks against your code.

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.
• Our bugs are currently under "Other Products", "Mozilla Services" or just bookmark "Add a bug" and "Browse bugs".
• 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 easiest way to do this is to add the default QA contact for each component to the list of users your are watching in Bugzilla
  • Open the list of Services 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 Mercurial

Mozilla's development process is very much patch driven. Mozilla uses Mercurial (as well as git for some projects) as the version control system. Mercurial Patch Queues, although a bit awkward to use at times, fit this process rather well. It is recommended you familiarize yourself with them and use them.

You can find the Services team's code repository at [1].

Configuration

Marco Bonardo has some general purpose tips for Mozilla developers on how to format patches before uploading them to Bugzilla.

Essentially it is recommended you put the following in your ~/.hgrc:

 [ui]
 username = Your Name <you@mozilla.com>
 
 [extensions]
 hgext.mq = 
 
 [diff]
 git = 1
 unified = 8
 
 [defaults]
 diff = -pU8
 qdiff = -pU8
 qnew = -U
 qseries = -sv

If you find yourself mixing up `hg qpush` (push a patch onto your queue) and `hg push` (irreversibly push your changes out into the world) try adding this:

 [hooks]
 preoutgoing.confirm = read -p 'Are you sure you want to push to remote? (y/n): '; echo $REPLY | grep -q 'y'

(Note from philikon: I consider this hook pretty much useless. Mercurial will warn and abort if you're trying to with patches applied. So if you have any applied patches, it's very hard to accidentally push them. If you don't have applied patches, you're most likely not to have anything the remote repo doesn't have either.)

Also, useful path definitions:

 [paths]
 try = ssh://hg.mozilla.org/try/
 places = ssh://hg.mozilla.org/projects/places/
 mc = ssh://hg.mozilla.org/mozilla-central/

Landing patches

You have items in a patch queue that you'd like to push to s-c. Here's the thorough set of steps to follow to get them into the tree (assuming you have commit access, of course).

Make sure services-central is open and green

Check TBPL.

Make sure your tree is up to date

 hg qpop --all
 hg pull -u

Make sure that all the patches have a proper commit message

For simple bugs, the format is

 Bug NNNNNN - Bug Summary here. r=your_reviewers_IRC_nickname

For bugs with several parts, you can do

 Bug NNNNNN - Bug Summary here. r=your_reviewers_IRC_nickname
 `
 Part X: Frobnicate the majiggaberator

Or simply

 Bug NNNNNN - Part X: Frobnicate the majiggaberator. r=your_reviewers_IRC_nickname

Run hg qser -sv (omit the -sv if you're using the config above). The output will look something like

 0 U favicons-1a: Bug 675996 - Part 1: extend moz_favicons with GUID to support Sync. r=mak
 1 U favicons-1b: Bug 675996 - Part 2: adjust Places migration tests to expect current version, not v11; tests for GUIDs in favicons. r=mak

If they don't, hg qpush each one and edit the summary with hg qref -e.

Ensure that the only patches you have applied are the ones you want to push

… and that they're the ones that were reviewed. You can reorder patches by hg qpop --all then hg qpush --move $patchname, or by manually reordering .hg/patches/series. Only edit the series file when all patches have been popped.

Applied patches are indicated by an 'A' in the 2nd column of qseries. Unapplied are 'U'.

Run tests

Now is a great time to run tests, because this is the state in which services-central will be after you push. If you apply a tests patch to re-enable disabled tests, make sure you pop it when you're done.

Finish the applied patches

 hg qfinish --applied

Verify what you're going to upload

 hg out

If the command shows anything other than the patches you're expecting (or they're wrong in some way), stop and ask for help.

Push!

If all is good, push:

 hg push

Repositories

Getting a checkout of a large Mercurial repository can be a pain if you're remote. Nobody wants to wait 6 hours while Python drools on its shoes. The answer is bundles. Follow the directions. The services-central bundle is here.

services-central

services-central is the clone of mozilla-central in which the Sync client (and other stable Services client-side projects) are developed.

Things that live there:

• The Services client libraries in services/crypto/ and services/sync.

• Built-in UI in browser/base/content/.

fx-sync

Sync was primarily developed in the fx-sync repository. The code there includes support for the Sync add-on; it's deprecated since Firefox 4.

Things that live there:

• The Services client libraries in services/crypto/ and services/sync.

• The Firefox Sync add-on in addon/*

• The Firefox 3.x and Fennec 1.x UIs for the Sync add-on in ui/*

mozilla-central

mozilla-central is the repository for Firefox and the base repository for other Mozilla-based applications. How mozilla-central is relevant to Sync:

• services-central is periodically merged into mozilla-central.

• The integrated UI for Firefox Sync lives in browser/base/*, along with the rest of the Firefox UI.

• Firefox releases are spun from mozilla-central. Changes made to services-central don't directly reach users.

Try server

Because Sync is developed in a clone of mozilla-central, you can use ordinary "try build" procedures to test your changes. (You don't always need to, though; one of the advantages of having an integration branch like services-central is that we're at liberty to break it!)

To push to try, teave your changes as applied mq patches. Then run:

 hg push -f ssh://hg.mozilla.org/try/

Testing

Writing xpcshell-based unit testing.

Collaboration

IRC

Being a geographically distributed group, we tend to hang out on IRC. One thing you may wish to consider is running an irssi client in a screen session on a shell host. Here's a truncated config file you can use to connect:

servers = (
 {
   address = "irc.mozilla.org";
   chatnet = "mozilla";
   port = "6697";
   autoconnect = "yes";
   use_ssl = "yes";
  }
 };
chatnets = { type = "IRC"; }; 

channels = { 
 {
   comment = "Public channel for Sync";
   name = "#sync";
   chatnet = "mozilla";
  }
  {
   comment = "Public channel for Identity";
   name = "#identity";
   chatnet = "mozilla";
  }
}

Meetings

• Services Weekly Status: Every Tuesday at 9:15 PT in North Bridge (4th floor), conference dial in number is #8616. Meeting notes live under Services/Meetings.
• Mozilla Weekly Updates: Every Monday at 11:00 PT in 10-Forward (you'll need to attend the first one in person since we want to show you off.)

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.