README for the CVS-support component of CVSZilla.
----------------------------------------------------------------------

1. Introduction
2. Installation instructions

======================================================================
1. Introduction

The software in this directory is used to keep track of CVS changes
by requiring the log message against each change to take a particular
format, and by storing details of each CVS commit in a SQL database.

It also integrates with Bugzilla to keep a detailed record of changes
made to the CVS repository for each bug.

Essentially, this code extends CVS to record de facto
poor-man's-transactions (something roughly analogous to a "change
set", in other words). Better than nothing, anyway.

You can run this without bugzilla, and you still get "change-sets",
but you'll have to hack on the code here by hand to remove the
bugzilla-specific parts.

This software is released under Perl's "Artistic License". Please see
http://www.perl.com/language/misc/Artistic.html for details.

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

That is, if this code breaks your repository, it's not my
fault. Similarly for s/repository/bugzilla/.

======================================================================
2. Installation instructions

You need to run these scripts on the same machine your CVS server is
sitting on. You will need to be able to access your Bugzilla MySQL
database either locally or via a network connection. You will need to
have the Perl MySQL access modules installed as for Bugzilla
itself. Also, you really need to have access to Bugzilla from the same
machine, since this script calls "processmail" from the Bugzilla
distribution to send out email notifications. Once you can satisfy all
the above:

1. Locate the path to the Bugzilla CGI binaries.
   Set $bugzilla_path in logmsg-parsing.pl to this path.
   (If you don't want to run on the same machine that has the Bugzilla
   CGIs, you'll need to hack out the part that calls the Bugzilla
   "processmail" script.)

2. Set @valid_cvs_roots to list all paths to the CVS repository we are
   being installed against. For instance, I run a CVS repository out
   of '/home/cvs', but it's really a symbolic link to
   '/volA/cvs'. Both paths need to appear in @valid_cvs_roots, since
   *most* of CVS will use the root it's given (ie. '/home/cvs') but
   parts of CVS ("rtag" especially) uses the real path underlying any
   symbolic links (ie. '/volA/cvs') and so we have to be prepared to
   accept both.

3. Decide on a transaction duration - basically the amount of time
   between fractional-commits that you want to allow before one
   transaction gets recorded as two. The default is 600 seconds,
   which is usually quite OK. If you have an excessively laggy
   network link, you *might* want to increase this. But it's unlikely.
   (The variable to change is logmsg-parsing.pl's
   $transaction_duration.)

4. Check the code near the bottom of logmsg-parsing.pl to make
   sure that it will be able to connect to your MySQL database
   okay. The line to check is:

   $db = Mysql->Connect("localhost", "vc", "vc", "")
       || diePrinting("Could not connect to VC database");

5. Install the database tables:

   $ mysqladmin create vc
   $ mysql vc < vcdb.sql

6. Create some general-jobs, if you want:

   $ mysql vc
   mysql> insert into general_jobs values (...);

7. Hook up the cvssupport code into CVS itself (here we assume that
   you've put the scripts in /usr/local/src/cvssupport):

   $ cvs co CVSROOT
   $ cd CVSROOT

   Put the line:
     ALL /usr/local/src/cvssupport/commit.branch ${USER}
   ...at the end of the file 'commitinfo', if you want ACL-style
   branch access restrictions. BE SURE TO READ THE COMMENTS AT THE TOP
   OF THE FILE 'commit.branch' BEFORE USING IT!

   Put the line:
     DEFAULT /usr/local/src/cvssupport/logmsg.archive ${USER} %{sVv}
   ...at the end of the file 'loginfo'.

   Put the line:
     DEFAULT /usr/local/src/cvssupport/tag.archive ${USER}
   ...at the end of the file 'taginfo', if you want tag logging.

   Put the line:
     DEFAULT /usr/local/src/cvssupport/logmsg.verify
   ...at the end of the file verifymsg'.

   Now commit those changes:
   $ cvs commit

   -----------------------------------------------------------------
   NOTE: At this point, *any* further commits to *any* module in the
   repository will be run through the log-message checker and
   archiver! You might want to test things on a dummy repository to
   get the hang of it before you put it into your main CVS repository.
   -----------------------------------------------------------------

That should be it. Any further CVS commits should now put entries into
tables vc.transactions, vc.job_xref, vc.transaction_entry etc etc.

  * If you are using commit.branch, be sure that you have patched your
    CVS server as recommended in the comments of commit.branch.

  * If you are using tag logging, any tags created will have
    associated entries in vc.taglogs, and moving non-temp ('te?mp_.*')
    tags or deleting any tags will be forbidden. Edit tag.archive to
    alter this behaviour.
