[Buildbot-commits] buildbot/docs buildbot.texinfo,1.107,1.108

[Brian Warner]

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

Modified Files:
	buildbot.texinfo 
Log Message:
[project @ buildbot.texinfo: more MaildirSource docs refactoring]

Original author: warner at lothar.com
Date: 2007-07-28 02:36:12+00:00

Index: buildbot.texinfo
===================================================================
RCS file: /cvsroot/buildbot/buildbot/docs/buildbot.texinfo,v
retrieving revision 1.107
retrieving revision 1.108
diff -u -d -r1.107 -r1.108
--- buildbot.texinfo	28 Jul 2007 02:03:09 -0000	1.107
+++ buildbot.texinfo	28 Jul 2007 02:37:14 -0000	1.108
@@ -160,7 +160,7 @@
 
 Parsing Email Change Messages
 
-* CVSToys MailNotification::    
+* FCMaildirSource::             
 * SyncmailMaildirSource::       
 * BonsaiMaildirSource::         
 
@@ -2719,7 +2719,18 @@
 parse the messages, which is highly dependent upon the tool that was
 used to create them. Each VC system has a collection of favorite
 change-emailing tools, and each has a slightly different format, so
-each has a different parsing function.
+each has a different parsing function. There is a separate
+ChangeSource variant for each parsing function.
+
+Once you've chosen a maildir location and a parsing function, create
+the change source and put it in the @code{c['sources']} list. Since
+buildmasters usually only have a single change source,
+ at code{c['sources']} can also be a single instance:
+
+ at example
+from buildbot.changes.mail import SyncmailMaildirSource
+c['sources'] = SyncmailMaildirSource("~/maildir-buildbot", prefix="/trunk/")
+ at end example
 
 @menu
 * Subscribing the Buildmaster::  
@@ -2800,11 +2811,11 @@
 @item CVS
 @table @samp
 @item CVSToys MailNotifier
-http://twistedmatrix.com/users/acapnotic/wares/code/CVSToys/
+ at ref{FCMaildirSource}
 @item Bonsai notification
-http://www.mozilla.org/bonsai.html
+ at ref{BonsaiMaildirSource}
 @item syncmail
-http://sourceforge.net/projects/cvs-syncmail
+ at ref{SyncmailMaildirSource}
 @end table
 
 @item SVN
@@ -2823,49 +2834,75 @@
 
 @end table
 
+Most of these parsers accept a @code{prefix=} argument, which is used
+to limit the set of files that the buildmaster pays attention to. This
+is most useful for systems like CVS and SVN which put multiple
+projects in a single repository (or use repository names to indicate
+branches). Each filename that appears in the email is tested against
+the prefix: if the filename does not start with the prefix, the file
+is ignored. If the filename @emph{does} start with the prefix, that
+prefix is stripped from the filename before any further processing is
+done. Thus the prefix usually ends with a slash.
+
+
 The following sections describe the parsers available for each of
 these tools.
 
 @menu
-* CVSToys MailNotification::    
+* FCMaildirSource::             
 * SyncmailMaildirSource::       
 * BonsaiMaildirSource::         
 @end menu
 
- at node CVSToys MailNotification, SyncmailMaildirSource, Parsing Email Change Messages, Parsing Email Change Messages
- at subsubsection CVSToys MailNotification
+ at node FCMaildirSource, SyncmailMaildirSource, Parsing Email Change Messages, Parsing Email Change Messages
+ at subsubsection FCMaildirSource
 
 
 @csindex buildbot.changes.mail.FCMaildirSource
 
-CVSToys also provides a @code{MailNotification} action which will send
-email to a list of recipients for each commit. This tends to work
-better than using @code{/bin/mail} from within the CVSROOT/loginfo
-file directly, as CVSToys will batch together all files changed during
-the same CVS invocation, and can provide more information (like
-creating a ViewCVS URL for each file changed).
+http://twistedmatrix.com/users/acapnotic/wares/code/CVSToys/
 
-The Buildbot's @code{FCMaildirSource} is a ChangeSource which knows
-how to parse these CVSToys messages and turn them into Change objects.
-It watches a Maildir for new messages.
+This parser works with the CVSToys @code{MailNotification} action,
+which will send email to a list of recipients for each commit. This
+tends to work better than using @code{/bin/mail} from within the
+CVSROOT/loginfo file directly, as CVSToys will batch together all
+files changed during the same CVS invocation, and can provide more
+information (like creating a ViewCVS URL for each file changed).
 
-The @code{FCMaildirSource} is created with two parameters: the
-directory name of the maildir root, and the prefix to strip.
+The Buildbot's @code{FCMaildirSource} knows for to parse these CVSToys
+messages and turn them into Change objects. It can be given two
+parameters: the directory name of the maildir root, and the prefix to
+strip.
 
- at node SyncmailMaildirSource, BonsaiMaildirSource, CVSToys MailNotification, Parsing Email Change Messages
+ at example
+from buildbot.changes.mail import FCMaildirSource
+c['sources'] = FCMaildirSource("~/maildir-buildbot")
+ at end example
+
+ at node SyncmailMaildirSource, BonsaiMaildirSource, FCMaildirSource, Parsing Email Change Messages
 @subsubsection SyncmailMaildirSource
 
 @csindex buildbot.changes.mail.SyncmailMaildirSource
 
- at code{SyncmailMaildirSource} knows how to parse the message format
-used in mail sent by Syncmail.
+http://sourceforge.net/projects/cvs-syncmail
+
+ at code{SyncmailMaildirSource} knows how to parse the message format used by
+the CVS ``syncmail'' script.
+
+ at example
+from buildbot.changes.mail import SyncmailMaildirSource
+c['sources'] = SyncmailMaildirSource("~/maildir-buildbot")
+ at end example
 
 @node BonsaiMaildirSource,  , SyncmailMaildirSource, Parsing Email Change Messages
 @subsubsection BonsaiMaildirSource
 
 @csindex buildbot.changes.mail.BonsaiMaildirSource
 
- at code{BonsaiMaildirSource} parses messages sent out by Bonsai.
+http://www.mozilla.org/bonsai.html
+
+ at code{bonsai_parser} parses messages sent out by Bonsai, the CVS
+tree-management system built by Mozilla.
 
 
 @node PBChangeSource, P4Source, Mail-parsing ChangeSources, Getting Source Code Changes