B2G/Hacking

Project overview

TODO WRITEME

Communication

Mozilla is an Open Source community. In that spirit, most communication happens out in the open (unless confidentiality is required, of course). This allows people in remote offices, people working from home, and community members alike to participate in all matters. Roughly speaking, the following forms of communication are used at Mozilla:

• IRC for ad-hoc conversations
• Bugzilla for tracking (Gecko) code changes
• GitHub for tracking B2G and Gonk code changes
• The public mailinglists for discussions
• This wiki for long-lived information, e.g. How-Tos, design documents, etc.
• MDN for technical documentation.

See below for details.

IRC

Conversations and ad-hoc coordination often happen on IRC. Most modules have their own IRC channels. The channels relevant to the B2G project are:

• #b2g
• #webapi
• #gaia

It is highly recommended to be present and, whenever relevant to one's work, also active on these channels. Keep in mind that these channels are publicly accessible.

Mailinglist

Mailinglists are used for discussions. The lists relevant to the B2G project are:

• https://lists.mozilla.org/listinfo/dev-b2g
• https://lists.mozilla.org/listinfo/dev-webapi

Team meetings

There's a weekly B2G meeting (as well as a weekly Gaia meeting). Please attend whichever meeting is relevant to you. Please keep the following points in mind:

• Please keep it short when you're speaking. The whole team is attending, that's a lot of people whose time and attention you have at that moment. Use it respectfully.
• Whenever you're *NOT* speaking, keep your handset *MUTED*.

Documentation

Documentation is maintained by Mozilla on the Boot to Gecko MDN page.

If you are just getting started, visit that page for instructions about how to set up your build environment and configure your device.

Tools

Bugzilla

Most code changes within the Mozilla project are tracked in Bugzilla. B2G is somewhat of an exception as it uses GitHub for the non-Gecko parts. All of Gecko is tracked in Bugzilla, however.

Basic workflow

• Every code change to Gecko must have a corresponding bug on file 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-inbound. If the changes pass the automated tests there, they will eventually be uplifted to mozilla-central which is the canonical repository for Gecko. If they don't pass the tests, they will be backed out.
• It is not uncommon to track bugs that are part of a larger, more long term project in so-called "tracking" or "meta" bugs. This allows people to watch the those meta/tracking bugs and receive updates whenever one of the dependencies change.

Get up to speed

• A good start is to go watch Jonath's "Bugzilla for Humans" video.
• 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, so for instance "Philipp von Weitershausen [:philikon]"
• You also want to watch the components relevant to your work so you automatically get emails for all bug changes in those components. You can component watching in the Buzilla preferences.
• Components to watch for B2G-related bugs:
  • Everything in the Boot2Gecko product (this product covers the top-level b2g directory in mozilla-central)
  • In the Core product, DOM: Device Interfaces is of the most interest. This is where device WebAPIs such as telephony, SMS, bluetooth, etc. are tracked.
• Meta bugs to watch:
  • bug 715781 - B2G milestone 1: developer phone
  • bug 715782 - B2G milestone 2: demo phone
  • bug 715784 - B2G milestone 3: product phone

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.

Gecko is developed in mozilla-central, though patches should be landed to mozilla-integration first so that they get appropriate test coverage before making it to the main tree.

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

Also, useful path definitions:

 [paths]
 try = ssh://hg.mozilla.org/try/
 inbound = ssh://hg.mozilla.org/integration/mozilla-inbound/
 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 the tree 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 the tree 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

Git

TODO WRITEME

Configuration

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

Setting up your development environment and building B2G =

Please see the Boot to Gecko page on the Mozilla Developer Network.

Hacking on ...

Gecko

TODO WRITEME

Gonk

TODO WRITEME

Gaia

Please see the Hacking on Gaia document.