View source for Labs/Ubiquity/Ubiquity 0.1 Development Tutorial

'''Note: these instructions cover development through current versions of Ubiquity, including versions 0.5.x.'''

If you just want to write new commands for Ubiquity, you should read [https://wiki.mozilla.org/Labs/Ubiquity/Ubiquity_0.1_Author_Tutorial the Command Author Tutorial] instead.  This page is about how to do development on the Ubiquity core.

= Getting Set Up =

== Getting the Source ==

It is pretty easy to get involved with the development of Ubiquity. Start off by introducing yourself on the irc channel [irc://irc.mozilla.org/ubiquity #ubiquity] on [http://irc.mozilla.org/ irc.mozilla.org].

You will need to have [http://www.python.org Python] installed, preferably Python 2.5.  (If you are on Mac OS X, you have Python already.)  We use Python instead of Make for our build script.

We use [http://www.selenic.com/mercurial/wiki/ Mercurial], called "Hg" for short, for version control. It is very easy to install if you've got Python 2.5 with setuptools. Just type:

  easy_install Mercurial

If you don't have setuptools, you can also install Hg the old-fashioned way, by downloading it from [http://www.selenic.com/mercurial/wiki/index.cgi/BinaryPackages www.selenic.com].

Once installed, you will be able to checkout the current source using the command:

  hg clone https://ubiquity.mozilla.com/hg/ubiquity-firefox

This will put a copy of the Ubiquity source into the home directory on your computer.  You need execute all the hg commands below from inside that directory.

== Installing the Source Version of the Extension ==

Uninstall your current version of Ubiquity from your Firefox Addons and then run:

  python manage.py install --profile=<profile name>

(Replace <profile name> with the name of the profile into which you prefer to install the extension.)

If you haven't created any profiles, then the profile you are using is called 'default'.  To install Ubiquity into the default profile, do this:

  python manage.py install --profile=default

This will generate a new build of the Ubiquity extension from the source checkout and install it with your local Firefox instance.

Now you are all set to become a pro Ubiquity hacker!

== Uninstalling Ubiquity ==

Just run

 python manage.py uninstall

optionally specifying a profile name/directory if necessary.  Alternatively, you can also uninstall the extension through the normal Firefox addon management UI.

== Building an XPI ==

You generally won't need to build an XPI when doing development, unless you're working on a final version intended for release to end-users.

To build an XPI for Ubiquity, just run:

  python manage.py xpi

This will create an XPI with the name "ubiquity-<version>.xpi", where
"<version>" is taken from the contents of the "em:version" element in the
"ubiquity/install.rdf" file.

= Development =

If you want to start writing code for Ubiquity, you <b>need</b> to follow the [http://developer.mozilla.org/en/JavaScript_style_guide Mozilla's Javascript style guide] (especially with respect to indentation and variable naming). This helps to maintain consistency in Ubiquity's code.

(TODO: find a style guide for HTML + CSS)

The heart of the code can be found in the subdirectories:

   ubiquity/modules/   
   ubiquity/chrome/content/

To get started, you may want to first take a look at the built-in and standard commands, which are in the files:

   ubiquity/builtin-feeds/builtincmds.js
   ubiquity/standard-feeds/*.js
   ubiquity/standard-feeds/*.xhtml

The feeds are dynamically loaded, so if you make any changes to them, all you have to do is save the file, then go back to Firefox and bring up Ubiquity again.  Your changes will be reflected immediately.  There's no need to rebuild your extension or restart Firefox.

If you make changes to other files -- parts of the core such as the parser or built-in nountypes, that are not dynamically loaded -- you will have to restart Firefox.  Even in this case, there is no need for you to keep on rebuilding your extension.  Once you've run python manage.py for the first time to install the extension, as described above, you shouldn't need to run it again.  Just save the source file and restart Firefox and whatever changes you've made will be reflected in Ubiquity.

== Don't Forget to Test ==

Make sure you run the test suite before committing your changes. From the root directory of your checkout, run:

    python manage.py test

That will only work if you have xpcshell installed.  If you have built Mozilla from source, you should have xpcshell on your system.  If you don't have it, another way to run the same test suite is by visiting this page:

  chrome://ubiquity/content/test.html

Due to slight differences between running javascript code in xpcshell on the command line, and running it in an html page, a test occasionally will fail on the html page even though it succeeds on the command line.  In that case, you can ignore the failure on the html page. To be specific, you can ignore the following error message:

 Error in test testSandboxSupportsJs17: missing ; before statement (in chrome://ubiquity/content/sandboxfactory.js, line 23)

== Keeping Up to Date ==

I recommend that you frequently update your repository to get the latest changes from the central repository.  In case you're not familiar with using Mercurial, pulling the code is a two-step process:

 hg pull
 hg update

You can also view the latest changes to the central repository on the web at [https://ubiquity.mozilla.com/hg/ubiquity-firefox/ ubiquity.mozilla.com].

== Finding Something to Work On ==

We use [http://wiki.mozilla.org/index.php?Ubiquity this Wiki] and [http://getsatisfaction.com/mozilla/products/mozilla_ubiquity GetSatisfaction] as places to get feature requests and bug reports. These feed into an internal Trac-based [https://ubiquity.mozilla.com/trac/report/1 ticketing system].

Login to [https://ubiquity.mozilla.com/trac/report/1 the Trac] using an OpenID account. Look for unassigned tickets (these are the ones that say "New" in the status column as opposed to "Assigned").  You can also search for the keyword "[http://ubiquity.mozilla.com/trac/search?q=good-for-beginners good-for-beginners]".  Check out what needs to be done, add things appropriately, choose unassigned tickets and start hacking!

== Submitting Patches ==

When you're starting out with development, you won't have push access to the central hg repository.  The best way for you to submit your changes is by creating a source code diff and attaching it to the Trac ticket that you're working on.  The command line is like this:

 hg diff > filename.diff

Note: In order for patches to be accepted, you <b>need</b> to follow the [http://developer.mozilla.org/en/JavaScript_style_guide Mozilla's Javascript style guide] (especially with respect to indentation and variable naming). This helps to maintain consistency in Ubiquity's code.

Then, on the Trac ticket page, click the "Attach file" button and choose the file you just created.  Add a bit of explanation about your changes, and click "Submit changes".  Don't change the status of the ticket yet.

One of the core developers will review your patch and, if it's found to be good, will commit it to the core repository and close the ticket.

After you've been developing for a while and have had some patches accepted, someone from the core development team (having noticed how awesome you are) will contact you to talk about getting you direct push access to the repository.