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

1,233 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.
@@ Line 5: / Line 7: @@
 == Getting the Source ==
-It is pretty easy to get involved with the development of Ubiquity. Start off by introducing yourself on the irc channel #ubiquity on [http://irc.mozilla.org/ irc.mozilla.org].
+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.
@@ Line 17: / Line 19: @@
 Once installed, you will be able to checkout the current source using the command:
-   hg clone http://hg.toolness.com/ubiquity-firefox
+   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 ==
@@ Line 23: / Line 27: @@
 Uninstall your current version of Ubiquity from your Firefox Addons and then run:
-   python manage.py install
+   python manage.py install --profile=<profile name>
-This will generate a new build of the Ubiquity extension from the source checkout and install it with your local Firefox instance.
+(Replace <profile name> with the name of the profile into which you prefer to install the extension.)
-If you have a separate profile that you'd prefer to install the
+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:
-extension under, such as 'testing', you can add that as an optional
-parameter:
-   python manage.py install testing
+   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!
@@ Line 44: / Line 48: @@
 == 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 build-xpi
+   python manage.py xpi
 This will create an XPI with the name "ubiquity-<version>.xpi", where
@@ Line 53: / Line 59: @@
 "ubiquity/install.rdf" file.
-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.
+= 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.
-= Development =
+(TODO: find a style guide for HTML + CSS)
-The heart of the code can be found in the subdirectory:
+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 commands and built-in noun types, which are in the files:
+To get started, you may want to first take a look at the built-in and standard commands, which are in the files:
-    ubiquity/chrome/content/builtincmds.js
+    ubiquity/builtin-feeds/builtincmds.js
-    ubiquity/chrome/content/nlparser/en/nountypes.js
+    ubiquity/standard-feeds/*.js
+   ubiquity/standard-feeds/*.xhtml
-These files 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 hit alt-space to bring up Ubiquity again.  Your changes will be reflected immediately.  There's no need to rebuild your extension or restart Firefox.
+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, 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.
+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 ==
@@ Line 91: / 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 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].
+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 the Trac [http://labs.toolness.com/trac/report/1] using an OpenID account. Look for unassigned tickets (these are the ones that say "New" in the status column as opposed to "Assigned").  Check out what needs to be done, add things appropriately, choose unassigned tickets and start hacking!
+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 ==
@@ Line 105: / Line 114: @@
   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.