Labs/Ubiquity/Ubiquity 0.1 Development Tutorial: Difference between revisions

← Older edit

Labs/Ubiquity/Ubiquity 0.1 Development Tutorial (view source)

Revision as of 15:46, 23 September 2009

4,586 bytes added , 23 September 2009

outdated info correction

Satyr

73

edits

@@ Line 1: / Line 1: @@
+'''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 ==
-To get the source code for Ubiquity and develop for it, you'll first have to install [http://www.selenic.com/mercurial/wiki/ Mercurial] and [http://python.org/ Python] if they're not already on your system.  Then, from the command line, enter:
+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].
-  hg clone http://hg.toolness.com/ubiquity-firefox
+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.
-Now enter the newly-created <code>ubiquity-firefox</code> directory and read the <code>README</code> file contained in it for further instructions (an online version can be found [http://hg.toolness.com/ubiquity-firefox/raw-file/tip/README here]).
+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:
-== Getting Involved ==
+  easy_install Mercurial
-It is pretty easy to get involved with the development of Ubiquity. Start off by introducing yourself on the irc channel #ubiquity on [[irc.mozilla.org]].
+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].
-We use Mercurial [http://www.selenic.com/mercurial/wiki/] for version control. It is very easy to install if you've got Python 2.5 with setuptools. Just type:
+Once installed, you will be able to checkout the current source using the command:
-   easy_install Mercurial
+   hg clone https://ubiquity.mozilla.com/hg/ubiquity-firefox
-Once installed, you will be able to checkout the current source using the command:
+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.
-  hg clone http://hg.toolness.com/ubiquity-firefox
+== Installing the Source Version of the Extension ==
 Uninstall your current version of Ubiquity from your Firefox Addons and then run:
-   python manage.py install
+   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 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!
+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.
-The heart of the code can be found in the subdirectory:
+= 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/
-We use this Wiki [http://wiki.mozilla.org/index.php?Ubiquity] and Getsatisfaction [http://getsatisfaction.com/mozilla/products/mozilla_ubiquity] as places to get feature requests and bug reports. These feed into an internal Trac-based ticketing system [http://labs.toolness.com/trac/report/1].
+To get started, you may want to first take a look at the built-in and standard commands, which are in the files:
-Login to the Trac [http://labs.toolness.com/trac/report/1] using an OpenID account. Check out what needs to be done, add things appropriately, choose unassigned tickets and start hacking!
+   ubiquity/builtin-feeds/builtincmds.js
+   ubiquity/standard-feeds/*.js
+   ubiquity/standard-feeds/*.xhtml
-Make sure you run the test suite before committing your changes:
+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
-Note: There is no need for you to keep on rebuilding your Extension after the first time. The changes to the manage.py built Extension are updated whenever you save updates to the source files and restart Firefox.
+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:
-Welcome to Ubiquity.
+ Error in test testSandboxSupportsJs17: missing ; before statement (in chrome://ubiquity/content/sandboxfactory.js, line 23)
 == Keeping Up to Date ==
@@ Line 50: / Line 101: @@
   hg update
-You can also view the latest changes to the central repository on the web at [http://hg.toolness.com/ubiquity-firefox/ hg.toolness.com].
+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.