B2G/Hacking

From MozillaWiki
< B2G
Jump to: navigation, search

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 and filing B2G bugs.
  • 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:

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:

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
showfunc = 1

[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/

Git

If you choose to hack on Gecko using git, you'll need to take care to attach patches to bugzilla in format others are expecting.

tl;dr: Use git bz attach from moz-git-tools to attach correctly-formatted patches to bugzilla.

Generating patches using git-diff

git diff defaults to 4 lines of context, but reviewers usually expect 8 lines of context in bugzilla. git diff also does not show file renames and copies by default. Reviewers will usually reject patches generated with these settings.

Instead of attaching the result of git diff to bugs, attach the output of the following command:

$ git diff -U8 --patience -M -C

You can alias this to git dif by modifying your ~/.gitconfig as follows:

[alias] dif = diff -U8 --patience -M -C

Generating checkin-needed patches

Patches generated using git diff are not suitable for checkin-needed, since they're missing the appropriate hg author and commit-message headers. The output of git format-patch (the equivalent of hg export) is also not suitable for checkin-needed, because hg can't read git's author and commit-message headers.

One way to generate a checkin-needed patche using git is to generate a file using git format-patch -U8 --patience -M -C and then run it through git patch-to-hg-patch from moz-git-tools. (I'd accept pull-requests to streamline this process.)

Alternatively, if you attach your patches using git bz attach from moz-git-tools, the patches will automagically have the correct format.

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 Treeherder.

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

TODO WRITEME

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.

Running tests

Mochitests

Reftests

Reftests are currently only supported on the emulator, though in theory they should run on other devices as well. 

pip install -r runreftest-requirements.txt
  • Either do:
cd objdir-gecko/_tests/reftest
ln -s <path_to_gecko_dir> tests
python runreftestsb2g.py --b2gpath <path_to_b2g_repo> --adbpath <path_to_adb_binary>
    --xre-path <path_to_firefox_objdir>/dist/bin --emulator arm --emulator-res 800x1000
    --remote-webserver 10.0.2.2 --ignore-windowsize <path_to_reftest_manifest>
    • xre-path is the path to a directory containing a desktop xpcshell binary. The one that is build with b2g will cause errors. Typically you can find it the objdir/dist/bin directory of a normal firefox build.
    • the reftest manifest is the path starting from the gecko root. E.g to run the main manifest you would put "layout/reftests/reftest.list"
  • OR, set the $B2G_PATH, $ADB_PATH and $MOZ_HOST_BIN (maps to --xre-path) environment variables. Then run:
export EXTRA_TEST_ARGS="--emulator arm --emulator-res 800x1000 --ignore-window-size" &&
    make -C objdir-gecko reftest-b2g
    • you can optionally also set $REFTEST_PATH to change the default manifest that gets run

Device API tests

xpcshell tests

I've run updater xpcshell tests both under the emulator and on a real device. I created a wiki page of notes for myself, since the second time I tried to do it I couldn't remember what I had done the first time.

Retrieved from "https://wiki.mozilla.org/index.php?title=B2G/Hacking&oldid=1043335"