# HG changeset patch
# User Jeff Hammel <jhammel@mozilla.com>
# Date 1296868486 28800
# Node ID 2d5b78d3411ca29ad56e0c30a541c2cfa9a735ba
# Parent  dc56c0de73bca16ebe6b9d52cbb1cfbc508c6ef1
explain how sources work

diff -r dc56c0de73bc -r 2d5b78d3411c README.txt
--- a/README.txt	Fri Feb 04 08:30:53 2011 -0800
+++ b/README.txt	Fri Feb 04 17:14:46 2011 -0800
@@ -181,6 +181,40 @@
 to see this location).
 
 
+Sources
+-------
+
+``autobot.process.factory:SourceFactory`` is an abstract base class
+for specifying sources.  Sources live as a member on the instance, named
+(oddly) ``sources``.  This is a dict with the key being the source
+type and the value being the source to use.  Source types are
+currently "git" and "hg", though this is easily extensible.  
+
+Internally, an individual source is stored as a 2-tuple with the first
+item being the URL of the source and the second item being the
+branch.  If the branch is ``None`` or not specified, this is assumed
+to equate to ``master`` for git or ``default`` for hg.  However, you
+may also use a string in the form of ``URL#branch``. In addition, you
+may specify a whitespace separated source, which ``SourceFactory``
+will split into a list of sources.  So all of these translate into the
+same source::
+
+ sources = {'hg': 'http://hg.mozilla.org/automation/logparser'}
+
+ sources = {'hg': ['http://hg.mozilla.org/automation/logparser#default']}
+
+ sources = {'hg': [('http://hg.mozilla.org/automation/logparser', None)]
+
+The generated ``master.cfg`` polls for changes on the given source,
+then uses ``buildbot.schedulers.filter:Changefilter`` in conjunction
+with a ``Scheduler`` to trigger the appropriate builds.
+
+While, in general, the canonical sources should be specified at the
+class level, if an appropriate argument (e.g. *hg* or *git*) is passed
+in to the ``SourceFactory`` constructor, this will override that
+source type.  This is useful for testing changes on non-canonical URLs
+and/or branches.
+
 
 Adding a New Project
 --------------------