[Buildbot-commits] buildbot/docs buildbot.texinfo,1.23,1.24

[Brian Warner]

Update of /cvsroot/buildbot/buildbot/docs
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv4679/docs

Modified Files:
	buildbot.texinfo 
Log Message:
Revision: arch at buildbot.sf.net--2004/buildbot--dev--0--patch-380
Creator:  Brian Warner <warner at lothar.com>

s/base_url/baseURL/ and s/default_branch/defaultBranch/ for SVN+Darcs

	* buildbot/process/step.py (SVN.__init__): change 'base_url' and
	'default_branch' argument names to 'baseURL' and 'defaultBranch',
	for consistency with other BuildStep arguments that use camelCase.
	Well, at least more of them use camelCase (like flunkOnWarnings)
	than don't.. I wish I'd picked one style and stuck with it
	earlier. Annoying, but it's best done before the release, since
	these arguments didn't exist at all in 0.6.6 .
	(Darcs): same
	* buildbot/test/test_vc.py (SVN.testCheckout): same
	(Darcs.testPatch): same
	* docs/buildbot.texinfo (SVN): document the change
	(Darcs): same, add some build-on-branch docs
	* docs/examples/twisted_master.cfg: match change


Index: buildbot.texinfo
===================================================================
RCS file: /cvsroot/buildbot/buildbot/docs/buildbot.texinfo,v
retrieving revision 1.23
retrieving revision 1.24
diff -u -d -r1.23 -r1.24
--- buildbot.texinfo	14 Oct 2005 19:42:40 -0000	1.23
+++ buildbot.texinfo	24 Oct 2005 22:42:03 -0000	1.24
@@ -2396,8 +2396,8 @@
 
 @cindex CVS Checkout
 
-The @code{CVS} build step performs a CVS checkout or update. It
-takes the following arguments:
+The @code{CVS} build step performs a @uref{http://www.nongnu.org/cvs/,
+CVS} checkout or update. It takes the following arguments:
 
 @table @code
 @item cvsroot
@@ -2431,7 +2431,8 @@
 
 @cindex SVN Checkout
 
-The @code{SVN} build step performs a Subversion checkout or update.
+The @code{SVN} build step performs a
+ at uref{http://subversion.tigris.org, Subversion} checkout or update.
 There are two basic ways of setting up the checkout step, depending
 upon whether you are using branches or not.
 
@@ -2453,17 +2454,17 @@
 @end table
 
 If, on the other hand, you are building from multiple branches, then
-you should create the @code{SVN} step with the @code{base_url} and
- at code{default_branch} arguments instead:
+you should create the @code{SVN} step with the @code{baseURL} and
+ at code{defaultBranch} arguments instead:
 
 @table @code
- at item base_url
+ at item baseURL
 (required): this specifies the base repository URL, to which a branch
 name will be appended. It should probably end in a slash.
 
- at item default_branch
+ at item defaultBranch
 this specifies the name of the branch to use when a Build does not
-provide one of its own. This will be appended to @code{base_url} to
+provide one of its own. This will be appended to @code{baseURL} to
 create the string that will be passed to the @code{svn checkout}
 command.
 @end table
@@ -2522,7 +2523,7 @@
 it to pay attention to all branches.
 
 The third piece is an @code{SVN} checkout step that is configured to
-handle the branches correctly, with a @code{base_url} value that
+handle the branches correctly, with a @code{baseURL} value that
 matches the way the ChangeSource splits each file's URL into base,
 branch, and file.
 
@@ -2538,8 +2539,8 @@
                        10*60, ['test-i386', 'test-ppc'])
 c['schedulers'] = [s]
 source = s(step.SVN, mode='update',
-           base_url='svn://svn.example.org/MyProject/',
-           default_branch='trunk')
+           baseURL='svn://svn.example.org/MyProject/',
+           defaultBranch='trunk')
 f = factory.BuildFactory([source,
                           s(step.Compile, command="make all"),
                           s(step.Test, command="make test")])
@@ -2553,7 +2554,7 @@
 
 In this example, when a change arrives with a @code{branch} attribute
 of ``trunk'', the resulting build will have an SVN step that
-concatenates ``svn://svn.example.org/MyProject/'' (the base_url) with
+concatenates ``svn://svn.example.org/MyProject/'' (the baseURL) with
 ``trunk'' (the branch name) to get the correct svn command. If the
 ``newthing'' branch has a change to ``src/foo.c'', then the SVN step
 will concatenate ``svn://svn.example.org/MyProject/'' with
@@ -2565,12 +2566,40 @@
 @cindex Darcs Checkout
 
 The @code{Darcs} build step performs a
- at uref{http://abridgegame.org/darcs/, Darcs} checkout or update. It
-takes the following arguments:
+ at uref{http://abridgegame.org/darcs/, Darcs} checkout or update.
+
+Like @xref{SVN}, this step can either be configured to always check
+out a specific tree, or set up to pull from a particular branch that
+gets specified separately for each build. Also like SVN, the
+repository URL given to Darcs is created by concatenating a
+ at code{baseURL} with the branch name, and if no particular branch is
+requested, it uses a @code{defaultBranch}. The only difference in
+usage is that each potential Darcs repository URL must point to a
+fully-fledged repository, whereas SVN URLs usually point to sub-trees
+of the main Subversion repository. In other words, doing an SVN
+checkout of @code{baseURL} is legal, but silly, since you'd probably
+wind up with a copy of every single branch in the whole repository.
+Doing a Darcs checkout of @code{baseURL} is just plain wrong, since
+the parent directory of a collection of Darcs repositories is not
+itself a valid repository.
+
+The Darcs step takes the following arguments:
 
 @table @code
 @item repourl
-(required): the URL at which the Darcs source repository is available.
+(required unless @code{baseURL} is provided): the URL at which the
+Darcs source repository is available.
+
+ at item baseURL
+(required unless @code{repourl} is provided): the base repository URL,
+to which a branch name will be appended. It should probably end in a
+slash.
+
+ at item defaultBranch
+(allowed only if @code{baseURL} is provided): this specifies the name
+of the branch to use when a Build does not provide one of its own.
+This will be appended to @code{baseURL} to create the string that will
+be passed to the @code{darcs get} command.
 @end table
 
 
@@ -2590,7 +2619,8 @@
 
 @item version
 (required): this specifies which ``development line'' (like a branch)
-should be used.
+should be used. This provides the default branch name, but individual
+builds may specify a different one.
 
 @item archive
 (optional): Each repository knows its own archive name. If this