Back in September, I wrote that I wasn’t leaving MDN. And, I’m not, really. But, it turns out that FirefoxOS needs some help to reach its first release milestones. So, some of us webdevs from around Mozilla are temporarily switching our daily efforts over to slay bugs on Gaia. That’s the layer of FirefoxOS which provides the overall system UI and core apps.

I’m planning to return to primarily MDN work in a few months – but, right now, FirefoxOS is kind of a big deal.

Thus, like some of my other colleagues in the past month, I’ve gone from being a fully-operational battle coder on a project with which I have years of experience, to being a total noob with no idea how to find my way to “Hello world”. It’s been awhile since I last parachuted into the middle of an open source combat zone, so I fell back to my training to get my bearings:

  1. Find the docs
  2. Get the source
  3. Run the project
  4. Break something, see what happens, fix it
  5. Fix a known bug, submit a patch
  6. Try to improve the process of fixing things

Finding the docs

Oddly enough, MDN was a good place to start for docs. Though, there are FirefoxOS docs spread between MDN, GitHub, and And, of course, they are each in various states of freshness and truthiness. Keep your wits about you; here be dragons.

Getting the source

Getting the source for FirefoxOS is a bit of a trick question – it depends on what you want to do, and how you want to contribute:

  • mozilla-b2g/B2G is the mother of all repos. Only start there if you’re brave & interested in the whole shebang. Fair warning, though: When the smoke cleared hours later, and the README was done with me, I had acquired 17G of new stuff in my dev directory. But, you’ll have ALL the things, and you can flash FirefoxOS to compatible hardware.
  • mozilla-b2g/gaia will be the most interesting if you’re like me and hoping to contribute as a webdev. That’s chock full of HTML, CSS, and JavaScript. It’s also pretty much free of pesky kernel code or device drivers that hurt my brain, because I’m not prepared to work at that low a level at this point in the morning.

There are other repos, for the Gonk and Gecko layers of FirefoxOS. But, for the sake of my sanity, I’m trying to avert my eyes for now.

Running the project

If you don’t have a compatible mobile device (and few do), you need a B2G Desktop build. While it’s true that many apps will run in Firefox Nightly, and there is an emulator you can build from the b2g repo, most apps are presently problematic in Firefox Nightly, and I’ve never gotten the emulator to build successfully.

You can either build your own B2G Desktop, or download a nightly build. I’ve done both, and generally I recommend sticking with the nightly Aurora builds.

On OS X, I was able to download a nightly build and launch it with a double-click. That got things running – hooray! But, it didn’t get me productive straight away: The nightly build comes equipped with its own embedded build of Gaia, which makes it handy for trying out your own 3rd party apps but not-so-handy for hacking on Gaia itself.

To improve this situation, you need to do two things:

  1. Build your own Gaia profile from your own clone of mozilla-b2g/gaia. This is pretty much just running make or DEBUG=1 make from your git clone.
  2. Run B2G Desktop from a terminal with command line options that tell it to use your new Gaia profile, rather than the built-in.

So, at this point, I have the Gaia source and a means by which to run it on my laptop.

Breaking things

After getting the project running as intended, I break something. And by that, I mean that I change a button title somewhere to “LOL BUTTS” or intentionally introduce an exception or syntax error somewhere. Then, I fix it. This is practice that exposes me to the guts of the thing; gets me into the edit/build/run cycle; shows me what it does when something goes wrong; and pushes me toward finding the tests.

But, I think I picked the wrong week to step into the arena, because everything came pre-broken. There were semi-known bugs preventing nightly builds of B2G Desktop from running my fresh clone of Gaia. It took me most of my first week to track down those bugs in bugzilla, find workarounds, and finally get something going. And then, it all broke again. And I found workarounds again.

Eventually, I was at a point where I built my own B2G Desktop from source with a particular patch from a particular bug applied, and that got me to the point where I could submit my first pull request to fix a broken test.

Happily, things seem to have stabilized since I started: B2G Desktop nightlies have been cooperating with bleeding-edge Gaia lately, so I’ve been able to stop building my own. So, now, when I find a combination of B2G Desktop and phone and Gaia checkout that works, I cling to that for dear life until it’s absolutely necessary for me to update one of the parts.

In short, FirefoxOS is very much in flux, right now. Bring a hard hat and expect delays.

Fixing things

Once I’ve broken something and then fixed it, I usually have a sense for how to get real work done. Since then, I’ve been slowly wrapping my head around the core Calendar app, and my bug fixes have finally started trickling in.

Cobbling together a reliable Gaia-hacking workflow is complicated, though:

  • Some Gaia apps work in Firefox Nightly, at least partially. This is great, because Firefox has all the great tools like the DOM inspector and web console. And, for the most part, you can just save-and-refresh to see changes.
  • All Gaia apps work in B2G Desktop, usually, though sometimes there are… quirks. This is good for seeing how changes work in a closer-to-real environment. But, B2G Desktop has none of the web developer tools offered by Firefox. And, to see changes, I generally have to save, relaunch B2G Desktop, then relaunch the app within the simulator. That’s pretty inconvenient.
  • All Gaia apps work on the Mozilla-supplied dev phone – which almost no one has. Well, they work more often than they do on B2G Desktop and Firefox, anyway. But, including a phone in the dev iteration loop is downright painful: As opposed to the usual webdev experience of save-and-refresh, the phone demands a save-build-flash-restart-relaunch cycle.
  • There is one awesome thing, at least for the Calendar app: There are unit tests which run in B2G Desktop, but are driven by a node.js controller in my shell. That lets me beat up on my code & logic in a “headless” context before jumping into Firefox, B2G Desktop, or the phone for a fuller integration test and a manual run-through. In fact, the unit testing framework even watches for file changes and will re-run tests right after a save, complete with a Growl notification of pass/fail.

Room for improvement

Slowly but surely, I’ve gotten my minigun barrel spun up to start firing piles of lead bullets at Gaia bugs. But, it has been and continues to be a challenge. I’m hard-pressed to recommend it as a fun-time leisure project to anyone without a Mozilla paycheck, or even as an off-hours interest for those who live-and-breathe Firefox. This is to be expected, since it’s not even a v1.0 project yet – but, I really, really hope things improve in the not-so-distant future.

  • We need to make sure that new contributors can get quickly from cloning the source to running the code. And it should always work – as in big, noisy automated tests fail when it breaks. I don’t care if it works fine on the phone if I can’t hack on it, at least from a contributor perspective.
  • We need a consistent and convenient development environment for Gaia. All day, I bounce between things that are partly broken in Firefox, partly broken in B2G Desktop, and mostly working on the phone. This kills productivity and enthusiasm, all day. And, many times, no one else in the #gaia channel on IRC knows what I’m on about when I say something’s broken – because everyone’s dev environment is a unique little snowflake.
  • My ideal workflow would never leave Firefox and my editor: Consider it a variant of the Responsive Design View, and ensure all the various APIs expected on a real phone are either working properly, polyfilled, or usefully stubbed out. Then, when it’s perfect in my most comfy environment, I can try it on a phone or standalone simulator as an afterthought. The upcoming built-in Firefox OS Simulator (née r2d2b2g) looks promising, but it needs to be seamless.

Still digging

Even with the challenges, and even if my contributions are small, I’m happy to have the opportunity to work on FirefoxOS. It’s a big deal; it’s the next Firefox. So, I plan to keep ramming my head against this stuff to help make it better, and I hope we can start taking time to make making it better better, too!