
CVS Brancher Overview and Usage
-------------------------------

Cvs Brancher is a tool to help with scheduled branching and merging of
CVS trees, such as for deploying changes to a website or a
cfengine-controlled data center at a particular time.

Background
==========
Many organizations make use of CVS for managing their website,
implemented as a set of flatfiles that are generated by a build script,
analogously to how software is built.  Others place the content into a
database, building each page on the fly as requested, caching the
generated pages for a time.  Each approach has pros and cons.  One of
the pros of the database-based approach is that it is reasonably easy to
specify that a given page should be visible only at a given time.

Cvs Brancher aims to make this scheduled-change feature possible for
CVS-based websites as well.  With CVS-based systems it can be a tad more
complicated; one would establish a branch, perform work on that branch,
and at the scheduled deployment time, the branch would be merged back
into the mainline, any build/test scripts run, and the new site
deployed.  Unfortunately, merging is error prone.  Algorithms in
version control systems such as CVS can safely handle many merge
situations, but there will always be some that require human judgement.
Because of this, it is necessary to detect if merging can be done
automatically or not, and if not, to take appropriate action such as
notifying a human and determining what to roll out (if anything),
temporarily. 

Cvs Builder is designed to address this issue.  


Applicability
=============
The pattern of storing files in CVS and running a command on its
contents to generate something is _certainly_ not unique to websites, so
this tool has broad applicability for other situations where changes
need to be done on branches and merged/built/deployed at a specific
time.  

For example, cfengine is a powerful tool for controlling the
configuration of a disparate number of machines in a data center.
cfengine uses a tree of config files to help it determine how to
customize various services, etc. for particular machines.  Storing these
files in CVS permits them to be version controlled.  Since these changes
can sometimes cause temporary downtimes, disconnections, etc. it can
sometimes be desirable to perform them on off hours.  Cvs-Brancher
enables the poor IT staff member to prepare these changes during normal
working hours, schedule them to be performed at the desired odd hour of
the night, and send an email to a pager if there's a problem.  

This may be useful for software testing as well.


Usage
=====

branch.pl
~~~~~~~~~
This is the primary tool for initiating a scheduled release.  The
purpose of this tool is to create a branch in CVS and set up an at-job
for calling scheduled_build.pl.

  % branch.pl osdl_extranet 01/23/03 05:00:00 \
    --cvs_root_dir=':pserver:www@cvs.pdx.osdl.net:/var/cvs' \
    --build_script='webbuild.sh' \
    --notify_from='cvs_brancher@osdl.org' \
    --notify_to='webmaster@osdl.org'

You may want to use a mailing list for the notify_to field, as this will
permit both archiving and a means of managing who does and does not
receive the messages.


scheduled_release.pl
~~~~~~~~~~~~~~~~~~~~
You normally will not use this tool; it is meant to be called as an
at-job that is prepared by branch.pl.  It can be run in a standalone
fashion (for testing or whatever); please refer to its manpage for
details. 

atq
~~~
This command lists the upcoming at-jobs on the machine.

  % atq

Note that this doesn't give details about the at-job in question; there
does not appear to be any way in at to store or retrieve additional
metadata.  This is another reason why it would be a good idea to direct
notices to a mailing list.

atrm
~~~~
This command can be used to remove at-jobs from the queue.  You can use
this to cancel any scheduled releases.  Note that if there are any
changes yet to be merged into the HEAD on the respective branch, you
will need to manually merge them back in.

  % atrm 42


System Configuration
~~~~~~~~~~~~~~~~~~~~
This is one way to configure a system using Cvs-Brancher for maintaining
a website stored in a CVS module named 'osdl_extranet'.  Terms in single
quotes are parameters specific to this example; replace with terms
appropriate to your environment.

0.  Install Cvs-Brancher and dependencies on machine 'webtest' as root
    See INSTALL for details.
1.  Create user 'cvssched' with CVS access to the CVS repository.  We
    will also use this as the From address for notification emails. 
2.  Log into machine 'webtest' as yourself.  I'm logging in as 'bryce'.
3.  Check out 

