# HG changeset patch
# User Jeff Hammel <jhammel@mozilla.com>
# Date 1296870045 28800
# Node ID 6606238e2b0710e05fa05dad7da44df5dceeeccd
# Parent  98e3594f29289447f61f84f2d5bf8c227a157a86
finish first-draft documentation, i think

diff -r 98e3594f2928 -r 6606238e2b07 README.txt
--- a/README.txt	Fri Feb 04 17:16:33 2011 -0800
+++ b/README.txt	Fri Feb 04 17:40:45 2011 -0800
@@ -237,6 +237,50 @@
 will find its way to a directory named for the project under
 ``autobot.projects``.
 
+Several factories (``BuildFactory`` descendents) are in
+``autobot.process`` to make building a new project easier:
+
+* ``SourceFactory``: as described above, this processes the sources
+  and gives a method (``checkout()``) for downloading them.
+  ``master.cfg`` looks in each factory and gleems its needed
+  repository from its ``sources`` attribute (if any) in the internal
+  storage mechanism of ``SourceFactory`` and sets up schedulers
+  accordingly. 
+
+* ``VirtualenvFactory``: inherits from ``SourceFactory``. creates a
+  python virtualenv and provides build properties ``%(virtualenv)s``,
+  ``%(python)s``, and ``%(scripts)s`` (location of ``bin`` on unix or
+  ``Scripts`` on windows with respect to the virtualenv.  It also has
+  a ``findScript()`` method which accepts the unix-style script name
+  (no extension) and returns the path to the script on the platform.
+
+* ``PythonSourceFactory``: inherits from ``VirtualenvFactory``. It
+  treats *all* (for now, can be changed) sources as sources of python
+  packages.  In addition to checking them out in
+  ``%(virtualenv)s/src``, it will also install them (using
+  ``%(python)s setup.py install``)
+
+* ``FirefoxDownloaderFactory``:  downloads and unpacks a Firefox
+  bundle, using 
+  `GetLatestTinderbox <http://hg.mozilla.org/automation/getlatest-tinderbox>`_ . 
+  It also provides three properties: ``%(firefox_url)s``,
+  ``%(firefox_bundle)s``, and ``%(firefox)s`` -- the last, and most
+  interesting, being the absolute path to the Firefox executable. You
+  (currently) *must* pass a ``platform`` argument with
+  ``platform['os']`` set to "linux", "win", or "mac" in order for
+  ``FirefoxDownloaderFactory`` to figure out what to do with the thing
+  that it downloads (though see TODO, in the future it should/could
+  use MozInfo or guess the OS from the bundle extension...maybe).
+  Currently, mac is *NOT* supported, though its on my list of things
+  to do (I'd love advice/help!).
+
+See the ``autobot.process.factory`` file for more details.  These
+classes are intended as mix-ins (not my favorite pattern, but it seems
+to basically be what buildbot wants you to do).  More work needs to be
+done to provide for the breadth of use-cases, but what exists now is
+considered a "good start" versus a "final form".  More factories may
+be added per necessity.
+
 
 Is your autobot being feisty?
 -----------------------------
@@ -253,6 +297,8 @@
 No software of any size is ever finished.  Here are a few things I
 would like to add:
 
+* get FirefoxDownloaderFactory working on Mac with .dmg files!
+
 * singular checkout of repos on slaves: the slaves should have a
   singular master repo that is checked out once for each repo URL,
   branch pair.  It is then updated as the slaves need and (e.g.)
diff -r 98e3594f2928 -r 6606238e2b07 autobot/process/factory.py
--- a/autobot/process/factory.py	Fri Feb 04 17:16:33 2011 -0800
+++ b/autobot/process/factory.py	Fri Feb 04 17:40:45 2011 -0800
@@ -31,7 +31,7 @@
     # must have the os specified!
     assert platform.get('os'), "platform['os'] must be one of (linux, win, mac); you have %s" % platform
 
-    # determine the (damn) url
+    # determine the url
     script = 'get-latest-tinderbox'
     if base_url:
       command = [script, '-u', base_url]