This is the top-level work page for the Tab Candy team.

Who

Aza Raskin, @azaaza, IRC: aza
Ian Gilman, @iangilman, IRC: iangilman
Michael Yoshitaka Erlewine, @themitcho, IRC: mitcho
Raymond Lee, @raymondlee, IRC: raymondlee
Sean Dunn, @somenotes, IRC: seandunn
Kevin Hanes, @mr_yuk

Important Pages

Design

Architecture

Tabs & Groups

Getting Started

Please "watch" the TabCandy component in Firefox in bugzilla by adding tabcandy@firefox.bugs at the bottom of: https://bugzilla.mozilla.org/userprefs.cgi?tab=email
Give yourself a nickname in bugzilla by going to https://bugzilla.mozilla.org/userprefs.cgi?tab=account and adding your IRC handle after a colon in square brackets after your name, e.g. Ian Gilman [:iangilman]. This makes it easier for people to assign bugs to you.

Development

These instructions assume you're on a Mac; please update with info for other platforms as needed.

TabCandy is part of Firefox, so to build it you need to build Firefox. Use the basic instructions.

You can work with the mozilla-central branch, but we also have a tabcandy-central branch (though it's currently frozen): ssh://hg.mozilla.org/users/edward.lee_engineering.uiuc.edu/tabcandy-central/

Once you've done a full build, for future builds you can just package up the various pieces TabCandy needs. One approach is to make a shell script like so:

make -s -j8 -C obj-ff-dbg/browser/locales && make -s -j8 -C obj-ff-dbg/browser/themes && make -s -j8 -C obj-ff-dbg/browser/base && make -s -j8 -C obj-ff-dbg/browser/app
obj-ff-dbg/dist/MinefieldDebug.app/Contents/MacOS/firefox-bin -no-remote -P tcc

This builds just the pieces needed (assuming your build directy is "obj-ff-dbg") and then launches the app (with a profile named "tcc").

Or, for those who didn't make a debug build the script would look like:

make -s -j8 -C objdir-ff-release/browser/locales && make -s -j8 -C objdir-ff-release/browser/themes && make -s -j8 -C objdir-ff-release/browser/base && make -s -j8 -C objdir-ff-release/browser/app
objdir-ff-release/dist/Minefield.app/Contents/MacOS/firefox-bin -no-remote -P tcc

You'll need to do a full rebuild every time you pull new code from mozilla-central, though.

The html and javascript files are in browser/base/content/tabview. The images and CSS file are in browser/themes/<platform>/browser/tabview. The tests are in browser/base/content/test/tabview.

Debugging

All of our JavaScript files get concatenated into a single tabcandy.js, so error line numbers don't line up with the original source files. You can, however, go to chrome://browser/content/tabview.js, hit "view source", and then command+L is "go to line".

Tests

Tabcandy test locations:

Our tests are located in browser/base/content/test/tabview with a small number in browser/base/content/test

Here are some tips on writing tests for Tab Candy:

Using setTimeout() to delay a finish() call is frowned upon. It covers up the underlying problem(s), and has a high potential of causing intermittent unit test failures.
To close a window, register an observer with the window watcher, as shown in the whenWindowObservesOnce() call in this attachment: https://bugzilla.mozilla.org/attachment.cgi?id=475327&action=diff and then call finish() once you've received a proper "domwindowclosed" notification for that window.

Here are some troubleshooting tips:

If your test spawns a window, you may notice that you get unexpected failures in the private browsing tests even if you properly clean it up. This is caused by unresolved closed windows in the session store. To remove this symptom from affecting later tests, use code such as that shown in this attachment: https://bugzilla.mozilla.org/attachment.cgi?id=475838&action=diff to clear the session store's record of closed windows before calling finish().

Mercurial Queues

Very handy for managing multiple patches in flight. Pop one on, work with it, pop it off again. See https://developer.mozilla.org/en/Mercurial_Queues to get started.

Once you have it all set up and do that init dance, you need to create the patch you'll be working on. You can either do this by doing hg qnew <patchname> (actually, we recommend hg qnew -U -e <patchname>, which will give the patch your username and give you a chance to enter its commit message) or by importing a patch. To import, grab the patch and hg qimport <patchname>.

Either way, you then apply the patch with hg qpush <patchname>, at which point you have the patch applied, and you can make live edits.

To update the patch do hg qrefresh. Edit, refresh, edit, refresh, etc.

To update the patch's commit message, do hg qref -e (which will open your editor).

When done, do hg qrefresh and then hg qpop. Now the patch is no longer being worked on. Grab the patch from .hg/patches/<patchname>.

Landing

Create a bug in bugzilla describing what your patch will do/fix, or use an existing bug if appropriate
If the patch fixes a bug or adds a feature (rather than, say, code clean-up, string changes, style changes, etc), it should have a unit test.
Regardless of whether you're adding a test, try all the browser chrome tests locally: make -C <objdir> mochitest-browser-chrome
Attach your patch to the bug and assign it for feedback from one of the Panorama team
Once you've got f+, mark it r? for review (ask in #tabcandy if you're not sure who to assign it to)
Once they've given you an r+, you'll need approval (unless it's already marked as a blocker, which means it's already approved for landing):
1. Mark it with a question mark under "approval 2.0", if the reviewer hasn't already done so
2. If it's a rush, poke someone to do the approval 2.0 (again, ask in #tabcandy if unsure who)
Push your patch to tryserver to make sure it doesn't break anything:
1. Update your m-c local repo
2. Apply the patch you would want to push to mozilla-central
3. hg push -f ssh://hg.mozilla.org/try
4. Check the results at: http://tests.themasta.com/tinderboxpushlog/?tree=MozillaTry
Once you've got your approval, make a fresh patch with the commit message giving the bug number and title (if you haven't already done that), and updated with [r=foo a=bar]
Mark the bug for checkin, by adding the keyword "checkin-needed" to it.
Add it as a "ride-along" on the landing queue: https://wiki.mozilla.org/LandingQueue
If it's urgent, poke someone who can land it

Also, make sure to read http://blog.bonardo.net/2010/06/22/so-youre-about-to-use-checkin-needed

Merging mozilla-central to tabcandy-central

Find a stable build at http://tests.themasta.com/tinderboxpushlog/ (no reds, no unstarred oranges, no gray Bs), and grab its revision number
Make sure your local tabcandy-central repo is up to date and there's no outgoing changes pending or uncommitted work
hg pull -r <revision> ssh://hg.mozilla.org/mozilla-central
hg merge
Fix conflicts if there are any (once you've fixed them, you can use hg resolve -ma to mark them all as resolved)
hg ci -m 'Merge mozilla-central to tabcandy-central.'
hg push

Also, don't forget to rebuild minefield with all the new code to make sure nothing's broken. Whether you do this before or after pushing is up to your sense of risk. :)

Code Documentation

You can find the documentation here.

We're using Natural Docs. There's a shell script (only tested on Mac) that runs Natural Docs on our code and converts the comments in the JavaScript to HTML docs. It'll generate a folder, naturaldocs-data, that'll be ignored by hg; you should ignore it too... it's just cache for the script.

Even though the TabCandy code is now in the tabcandy-central branch, we're still keeping the documentation in the old tabcandy branch. The docs script, tcc-docs.sh, assumes your tabcandy-central folder is next to your tabcandy folder.

Style Guide

Use spaces, not tabs, with two spaces per "tab stop".

80 character line length limit.

Prefer native methods over libraries where appropriate. For instance, use Array.forEach() rather than iQ.each() (note that for each(...in...) has issues and should generally be avoided).

Firefox/Projects/TabCandy/Work

Who