[kaffe-siteadmin] CVS kaffe-project-services (jim): Update README

[Kaffe CVS]

PatchSet 3 
Date: 2004/01/14 21:58:05
Author: jim
Branch: HEAD
Tag: (none) 
Log:
Update README

Members: 
	loginfo-cvsps/README:1.1->1.2 

Index: kaffe-project-services/loginfo-cvsps/README
diff -u kaffe-project-services/loginfo-cvsps/README:1.1 kaffe-project-services/loginfo-cvsps/README:1.2
--- kaffe-project-services/loginfo-cvsps/README:1.1	Wed Jan 14 17:15:03 2004
+++ kaffe-project-services/loginfo-cvsps/README	Wed Jan 14 21:58:05 2004
@@ -14,7 +14,7 @@
 Normally, CVS doesn't retain this information at checkin time (it's just
 a bunch of directories with RCS files, really), so it must be deduced.
 
-Warning:  What I am about to describe is a bit of "Rude-Goldberg" setup,
+Warning:  What I am about to describe is a bit of "Rube-Goldberg" setup,
 and is somewhat tricky to setup, and it's got some problems, which I
 will try to note.
 
@@ -30,6 +30,85 @@
 take a rather long time to run sometimes (especially when it is first
 building its cache).  It was also very error prone.
 
+So, what I did was to keep the old "martin-log.pl" script, and modified
+it to send an email to a new "resend at kaffe.org" user, which does the
+extra processing, after the commit has been made.
 
-(to be continued...)
+The "resend at kaffe.org" user has the following files in it's home
+directory:
+
+  /home/resend -+- .forward
+		+- bin --- incoming-mail.pl
+		+- log --- mail.log
+		+- .cvsps
+		+- checked-out -+- kaffe
+				+- kaffe-extras
+				+- kaffe-project-services
+				+- testing
+				+- website
+
+The ".forward" file simple pipes all the incoming email to "resend at kaffe.org"
+to the incoming-mail.pl script:
+
+-- start .forward --
+| /home/resend/bin/incoming-mail.pl
+-- end .forward --
+
+The "incoming-mail.pl" perl script is the guts of the operation.  It does
+the following:
+
+ * parses the incoming email (generated by the "martin-log.pl" loginfo
+   script), making sure that it comes from the appropriate source, and that
+   it is valid.  It looks at the files that were modified/added/deleted in
+   the commit, and saves them in a data structure for later.
+
+ * it runs "cvsps" on the appropriate module of the CVS.  The cvsps program
+   needs to operate against a checked-out tree.  These are located
+   in /home/resend/checked-out/<module-name>.  The version of cvsps I'm
+   currently using is 2.0rc1.  The cvsps program stores a cache of it's
+   results in /home/resend/.cvsps 
+
+ * it analyzes the output of the cvsps program and tries to match the
+   commit recieved in the email against a changeset from cvsps
+
+ * it composes an email to be sent to a mailing list containing a diff
+   for the found changeset.  If the diff is too long, it is truncated.
+
+ * the script generates a log in /home/resend/log/mail.log
+
+Some known problems:
+
+ * The script seems to fail for commits done on a branch.
+
+ * No locking is done.  This might be an issue if two commits happen
+   close together.  It might be possible for multiple instances of the
+   script to be running at the same time.  In the worst case, this might
+   cause the .cvsps cache to get corrupt, or to cause bogus output.  This
+   hasn't been tested much -- the Kaffe project typically only gets a
+   few commits a day, so there isn't much contention.
+
+ * Some random failures have been seen, but I didn't have time to
+   investigate.
+
+ * There were some stray lock files left in the CVS repository on several
+   occassions which were blocking commits which had to be manually
+   removed.  I suspect they were probably due to the script.
+
+ * The matching process is not 100% accurate.  For example, cvsps may
+   interpret two commits that happened close together as a single
+   changeset, so it will not be possible to match that with the two
+   emails that will come into the script.  There are probably other
+   situations were a match may not be possible.
+
+It seems to work OK for the purposes I'm using it for -- I'm not
+to concerned about 100% accuracy.  If a few of the generated emails
+come out broken, it's not too big of a deal.
+
+If anybody wants to modify these scripts, feel free to.  All of the
+stuff I wrote (basically "incoming-mail.pl") I place into the public
+domain.
+
+Cheers,
+
+ - Jim