ic_howto_cvs.sdf

!init OPT_LOOK="icdevgroup"; OPT_STYLE="manual"
# $Id: ic_howto_cvs.sdf,v 1.16 2004-05-05 15:22:29 jon Exp $

!define DOC_NAME "Interchange + CVS HOWTO"
!define DOC_TYPE ""
!define DOC_CODE "ic_howto_cvs"
!define DOC_VERSION substr('$Revision: 1.16 $', 11, -2)
!define DOC_STATUS "Draft"
!define DOC_PROJECT "Interchange"
!define DOC_URL "http://www.icdevgroup.org/doc/ic_howto_cvs.html"
!define DOC_OWNER "2001 Dan Browning E<lt>{{EMAIL:dan.browning@kavod.com}}E<gt>"
!build_title

H1: Introduction

H2: Preamble

N:Copyright 2001-2003 Dan Browning <dan.browning@kavod.com>.  This document is
freely redistributable under terms of the GNU General Public License. 

H2: Purpose

N:The purpose of this document is to help others take advantage of CVS and
Interchange together to increase the quality of their programming, whether they
are sole developers or part of a large team of programmers, graphic artists,
and HTML design gurus.  Portions of it apply to general CVS setup and use, but
it is geared toward the average developer using Interchange to implement an
e-commerce website.     

H2: Audience

N:I intend for this document to be useful to those who are not yet familiar
with CVS as well as those who are.  If you already know how to setup a pserver
then you might just skim chapter 2 ("Setup CVS"), or skip it all together.  

N:In addition, I have tried to write at a technical level that would be on par
with what I perceive to be the average Interchange user that participates on
the interchange-users mailing list.  It is assumed that the reader can and
already has setup Interchange and the template catalog (e.g. Foundation) is
working correctly.    

H2: Contact the author

N:If you find any spelling errors, technical slip-ups, mistakes, subliminal 
messages, or if you wish to send feedback, critique, remarks, comments, or if
you wish to contribute examples, instructions for alternative platforms, 
chapters, or other material, please do so.       

N:The preferred method of submitting changes is in the form of a context diff
against the SDF source file (ic_cvs.sdf).  Please address your correspondence
to:  

N:Dan Browning {{EMAIL:dan.browning@kavod.com}}

H2: The advantages of using CVS

N:CVS is a very useful tool and can help you in your development, no matter if
you are an independant developer or are part of a team of developers.  

*What is CVS all about?

*What are its advantages?  

N:The official CVS website ({{URL:http://www.cvshome.org/new_users.html}}) has 
more detailed answers to these questions, but here are some brief points of
interest. 

*Checkout "historic" points in time or milestones in a project, for example
when an e-commerce site went "live" or before a major branch in the code. 

*Revert to older versions of a file, directory, or an entire website.

*Branching releases.  Concurrently develop an unstable development version as
well as fix bugs in the stable production version. 

*Multiple developers can work on the same catalog and even the same file at the
same time.  (For more information about how multiple simultaneous writes are
merged and conflicts resolved, see the CVS docs in the {{SECT:Resources}}
Appendix).   

*CVS is better than ftp for file transfer, because it automatically downloads
only changed files, and even then, only the portion of the file that has
changed (using patches).  

*CVS can automatically merge two simultaneous writes to the same file by
different developers. 

*Allows one to keep track of the changes that have been made over time (many
release managers repackage CVS commit logs into WHATSNEW, HISTORY, and/or NEWS
files).  

H2: How to use this document

N:There are many potential uses of CVS as it applies to Interchange.  In fact,
there are as many unique ways to use CVS as there are unique developers.  This
document only covers some of the ways, including basic and useful techniques to
get started using CVS.  For the intents of the average web developer using IC
for a B2C e-commerce site, I've identified a few of the possible uses:    

N:Simple
	*One server
	*One catalog
	*One CVS module
	*One branch
N:Medium 
	*One server
	*Two catalogs (e.g., one is live, one is development)
	*Two CVS modules
	*Separate development and live branches
N:Complex/Custom
	*Multiple servers (e.g., developers' servers, staging servers, and live
	servers) 
	*Multiple catalogs
	*Multiple CVS modules
	*Multiple branches
	*Custom setup

N:This document attempts to cover the simple well, explain many aspects of the
medium, and hopefully give you the background you need if you decide to setup
your own complex development environment.  

H1: Setup CVS

H2: Assumptions

N:Here are some of the assumptions that I make that apply to various parts of
the rest of this document: 
*Red Hat Linux 7.x
*Interchange installed (RPM or tarball)
*Default Interchange tarball installation directory paths (adjust for your
environment) 
*Template catalog setup and working

Note:I will assume "foundation" for the catalog name and directory paths, but
it should be just as easy to use this document with your own catalog by
mentally transposing the names and paths.  

N:There shouldn't be any reason why you could not do everything I mention here
on other Linux distributions, Unices or Windows (using cygwin). However, my
statements will reflect Red Hat Linux 7.x. Additionally, Red Hat Linux 6.x is
for the most part the same as 7.x, except for the difference of using inetd
instead of xinetd to setup pserver.

H2: Install CVS

N:This is the easy part.  For Red Hat Linux systems, download the CVS rpms and 
install them.  You can search for rpms for your system using 
{{URL:http://www.rpmfind.net}}.

N:Create the user and group that will administrate the Interchange repository.
For this document, it will be the interch user, (which was setup during the
installation of Interchange).  But if you understand the mechanics of Unix
users/groups, then you can use whatever username and group scheme you prefer.
For example, some create a cvs user and add it to the same group that 
interchange uses (e.g. interch), or add the Interchange user and catalog owner 
to its group or vice-versa.  The integration of Interchange and CVS in the 
latter portion of this document will require that the CVS user can write to the
catalog directory.       

H2: Create the CVS repository directory

N:You will need to create a repository directory such as 
{{F:/home/interch/rep}}, which is used here and in the rest of the 
document, but it can be any directory you desire, and must be owned by the cvs
user.    

!block example;
	mkdir /home/interch/rep
!endblock

H2: Setup environment variables

N:The CVSROOT environment variable can be setup for your user (in {{F:~/.bashrc}} or {{F:~/.profile}}, or for all users in {{F:/etc/profile}}.

!block example;
{{B:~/.profile:}}

export CVSROOT=${HOME}/rep
!endblock

H3: .cvsrc

We recommend these default options for CVS.

!block example;
{{B:~/.cvsrc:}}

cvs -q
diff -u
update -Pd
checkout -P
!endblock

N: This directs CVS to (1) automatically compress all data communicated between
you and our server (saving bandwidth), and be quieter; (2) show 
context-sensitive diffs; (3) prune empty directories and create any new 
directories added to the repository since your checkout; and (4) prune empty 
directories during your checkouts.

Note:You will need to logout/login for the profile changes to take effect. 

H2: Initialize the repository

N:Initialize the repository as the CVS user, which is {{EX:interch}} for this
document. 

!block example;
	cvs -d /home/interch/rep init
!endblock

H2: CVS Authentication

H3:Background

N:Authentication is done in CVS through the {{F:$CVSROOT/CVSROOT/passwd}} file.  
It can be easily manipulated through some of the CVS administration tools that 
are available.  An alternate authentication method is ssh, which requires no 
extra setup on the server side. 

H3:CVS administration tools

*{{URL:http://freshmeat.net/projects/cvsadmin/}}
*{{URL:http://freshmeat.net/projects/cvspadm/}}

N:I recommend cvsadmin, but there are also a variety of manual methods that can
be used in the absence of such tools, one of which involves copying the system
shadow file and modifying it for use by CVS.  For more information on this
manual method, see the Red Hat CVS pserver setup guide by Michael Amorose
({{URL:http://www.michael-amorose.com/cvs/}}).    

H3:Setup authentication using the cvsadmin tool

N:You can find a tarball to install on your system using the above address, but
here is the address of a recent RPM package of the version. This package is
intended for Mandrake systems, but is compatible with Red Hat Linux 7.1:  

*{{URL:ftp://rpmfind.net/linux/Mandrake/9.0/contrib/RPMS/cvsadmin-1.0.2-1mdk.i586.rpm}}

N:After installing, create a password file 
({{touch $CVSROOT/CVSROOT/passwd, touch $CVSROOT/CVSROOT/users}}), 
and execute {{EX:cvsadmin add <usernames>}}.

H2: Setup CVS modules

Note:From this point on, assume that all commands are executed as the CVS user 
(e.g. interch), unless otherwise specified.

N:A module is CVS is like the concept of a "project", where each module has its
own branches, trees,  and other features. 

H3:Add your project to the {{F:modules}} configuration file

N:The format of the modules file is explained in detail in the CVS
documentation, here is the simplest way to use it.  First you will need to 
checkout your CVSROOT directory, then modify and commit the 'modules' file. 

!block example;

cvs co CVSROOT
cd CVSROOT

{{B:modules:}}


<Module name><TAB><Module Directory>
!endblock

N:The module name can be whatever you want, and the module directory is what we
will create later under /rep.  We'll want a module for the template catalog
(foundation).  For example:  

E:foundation	foundation

H3:Create the module directory

N: This is the directory that is referred to in the {{F:CVSROOT/modules}} file
we just modified. 

E:mkdir /rep/foundation

H2: Setup binary file types

N:This isn't necessary if you aren't going to manage any binary files (e.g. if
you plan on excluding your images/ directory).  But I recommend including it.
The following is an example including many binary file types (by extension)
used in web development.   

!block example;
{{B:/rep/CVSROOT/cvswrappers:}}

*.avi   -k 'b' -m 'COPY'
*.doc   -k 'b' -m 'COPY'
*.exe   -k 'b' -m 'COPY'
*.gif   -k 'b' -m 'COPY'
*.gz    -k 'b' -m 'COPY'
*.hqx   -k 'b' -m 'COPY'
*.jar   -k 'b' -m 'COPY'
*.jpeg  -k 'b' -m 'COPY'
*.jpg   -k 'b' -m 'COPY'
*.mov   -k 'b' -m 'COPY'
*.mpg   -k 'b' -m 'COPY'
*.pdf   -k 'b' -m 'COPY'
*.png   -k 'b' -m 'COPY'
*.ppt   -k 'b' -m 'COPY'
*.sit   -k 'b' -m 'COPY'
*.swf   -k 'b' -m 'COPY'
*.tar   -k 'b' -m 'COPY'
*.tgz   -k 'b' -m 'COPY'
*.tif   -k 'b' -m 'COPY'
*.tiff  -k 'b' -m 'COPY'
*.xbm   -k 'b' -m 'COPY'
*.xls   -k 'b' -m 'COPY'
*.zip   -k 'b' -m 'COPY'
!endblock

H3: Commit changes

Remember to commit the changes you made to 'modules' and 'cvswrappers'.

E:cvs commit -m "Update modules and binary types" modules cvswrappers  

H2:Setup the CVS pserver

N:You will likely need to be root to do this, and there are lots of guides on
the Internet for setting up a CVS pserver, hopefully you wont have any trouble
doing it on your particular operating system.  See the {{SECT:Resources}}
Appendix for more information.   

H3:Setup pserver in Red Hat Linux 7.x using xinetd. 

N:For Red Hat Linux 7.x, edit {{F:/etc/xinetd.d/cvspserver}} (create a new one
if none exists).  The following works for me, but customization may be required
for your environment (see the next section below for an inetd-based system
example).  This also must be done as root.   Remember to substitue 
/home/interch/rep with your repository directory below. 

!block example;
su - root
{{B:/etc/xinetd.d/cvspserver:}}

service cvspserver
{
        disable = no
        socket_type  = stream
        protocol  = tcp
        wait   = no
        user    = root
        server   = /usr/bin/cvs
        server_args  = -f --allow-root=/home/interch/rep pserver
}
!endblock

N:Now, restart xinetd for the changes to take effect. 

E:service xinetd restart	

H3:Setup pserver in inetd-based systems.

N:For inetd-based systems such as Red Hat Linux 6.2, make sure that the
following files are setup accordingly. 

!block example;
{{B:/etc/services:}}

cvspserver	2401/tcp
!endblock

!block example;
N:{{B:/etc/inetd.conf:}}

cvspserver stream tcp nowait \
	root /usr/sbin/tcpd /usr/bin/cvs \
	--allow-root=/home/interch/rep pserver 
!endblock

H3:Testing your pserver

N:At this point, you should be able to use a CVS client to use your pserver and
execute all the same commands that you can locally (which we tested before).
You may wish to take advantage of a graphical CVS client, which can be
particularly helpful in leveling the learning curve.   

Your pserver connection string will something along the lines of:

E: :pserver:<USERNAME>@<SERVER>:/home/interch/rep

N:See the {{SECT:Resources}} Appendix for links to some graphical CVS tools.

H1:Import your Interchange catalog into CVS

H2:Configuring your catalog

N:Eventually, we will import your catalog into the CVS repository, but first we
need to do some work with a temporary copy of the catalog so we can get it into
shape for importing.  

Note:From here on, assume the use of the Interchange user, such as
{{EX:interch}}, unless otherwise noted. 

E:su - interch

N:If you installed via RPM:

E:service interchange stop

N:If you installed via tarball (default path):

E:/usr/local/interchange/bin/interchange --stop

H2:Remove old CVS folders

N:If, for any reason, you already have {{EX:CVS/}} directories in your catalog,
they must be removed because they might interfere with the new CVS setup.  
You might use the following {{EX:find}} command, which will find any folders 
named {{EX:CVS}} in the current directory and remove them.

sNote:You should make a backup of the catalog directory before you do this.

!block example;

#backup catalog folder first
tar czf ~/foundation_backup.tgz /var/lib/interchange/foundation

#get rid of any old CVS folders -- (BE CAREFUL!)
cd /var/lib/interchange/foundation
find . -name CVS -exec rm -Rf {} \;
!endblock

H2:Create a working copy of your catalog

N:A working copy of your catalog is necessary to get it into shape for use with
CVS.  The following command creates a copy in the {{EX:/tmp}} directory.  

!block example;
cp -a /var/lib/interchange/foundation /tmp/import_foundation
cd /tmp/import_foundation
!endblock 

H2:Streamline your catalog for CVS

H3:Considerations about what to import into CVS

N:From your working directory ({{EX:/tmp/import_foundation}}), decide which
files will be in the CVS repository, and which will not.  While it is entirely
possible to import the entire catalog into the repository unchanged, I usually
prefer to doctor my directories up before letting them into my repository
because of several reasons:    

*Will the file be modified by another source?

N:For example, {{EX:/etc/order.number}} is modified by Interchange when run.  
It is recommended that the CVSIGNORE features be used to handle these types of 
files.  See {{SECT:CVSIGNORE}}. 

*The likelihood that you will modify the file.

N:For example, if I am certain that I wont every want to modify the session/
files directly, then I probably wouldn't need to manage that through CVS, but I
do import the empty session/ directory to make it easier when setting up new
catalogs.   

*Speed.

N:Managing less files in the repository takes away from the amount of time
required for CVS checkout, update, branching, and other CVS actions.  For most,
this amount of time is small already, but it is a consideration for some.  
If you have a very large image directory, it may be benificial to leave it out 
at first.  Note that you can add or remove anything later on.  
		
H3:Remove files that aren't needed in CVS

N:Here is an example of some things to remove from your catalog.  If you do move more
directories, be sure to move them to a directory that you can later use to
re-unite with a checked-out copy for a working catalog.  But here I chose just
to move files that are not needed for a template "skeleton" catalog.    

N:If you want to add images to your repository, the images directory is typically symlinked to
/var/www/html/foundation/images, so I remove this symlink from the working
copy, and replace it with an exact copy which will go into the CVS repository.  

!block example;
#Setup images directory
rm images
cp -a /var/www/html/foundation/images .

#Remove 
rm -Rf \
	error.log \
	*.structure \
	orders/* \
	logs/* \
	session/* \
	tmp/* \
	upload/* \
	backup/* \
	logs/* \
	#done.
	
# The ".empty" files make it so that CVS will still checkout the
# directory, even though it is empty.
touch \
	orders/.empty \ 
	logs/.empty \ 
	session/.empty \ 
	tmp/.empty \ 
	upload/.empty \
	backup/.empty \
	#done.

!endblock

H2:Import the streamlined catalog

N:Import the remaining portion of the catalog using the {{EX:cvs import}}
command, with "foundation" as the module name and repository directory name.
See the CVS documentation resources mentioned in Appendix {{SECT:Resources}}
for more information.    

N:When you run the import command, it will launch $EDITOR (set to {{EX:'vi'}}
earlier), and ask for a message to go along with the import action.  Whatever
you see fit to write (e.g. "starting new CVS module with my foundation
catalog...") is fine.   

N:This example {{EX:import}} command includes renaming the foundation "working"
directory back to "foundation" for the import. 

E:cvs import foundation foundation start

H2:Testing the new CVS module

N:Now you should be able to do another test checkout or update using any CVS
client, which should now download all the files that you have just imported
into CVS.  Additionally, you might test your newly imported code by making a
change to one of your checked-out source files, saving it, then committing it.
 
!block example;
{{B:index.html:}}
<!--this is a test comment at the top of index.html-->
!endblock

N:Now commit the change

{{EX:cvs commit index.html}}

N:Your changed version will now be resident in the repository.  There are a lot 
of good CVS documentation and resources for discovering more about the 
checkout/update/commit cycle and other CVS aspects in the {{SECT:Resources}} 
Appendix  

N:You'll also notice that even if you start your interchange server, the change
you made did not take effect.  The next section will detail the process of
tying CVS and Interchange together in a way that this will happen automatically.  

H1:Integrate CVS and Interchange

N:The next step is to allow CVS to update the directory that Interchange uses
to serve pages. 

H2:CVS checkout into the catalog directory

N:Now it is the time to replace the directories in your catalog that have
counterparts in CVS with fresh checkouts from CVS (this is a preliminary action
to allow CVS to update your catalog directory when a change is made to CVS).  

Note:Make sure interchange daemon is stopped and you have a good backup before
continuing. 

{{EX:tar czf ~/foundation.backup2.tgz /var/lib/interchange/foundation}}

N:Checkout a copy from CVS into a different directory (such as
{{F:foundation_CVS}}). 

!block example;
cd /var/lib/interchange/
cvs co -d foundation_CVS foundation
!endblock

N:This should create the {{F:foundation_CVS/}} directory for you, so that it
wont conflict with your existing {{F:foundation/}} directory.   

H3:Add any needed files to checked-out catalog

Note that empty directories are pruned, so they will need something in them for
them to show up with a -P checkout. Often a zero-byte file called '.empty' is
used.  

N:If you removed any directories during the streamlining step, we must first
add those back so that the catalog is usable to Interchange.  In this document,
we only removed unneeded files and left empty directories.  

N:This can also be the time to copy any "data" files such as orders/ logs/,
etc. that might be needed if it is a live catalog. 

!block example;
cd /var/lib/interchange/foundation
cp -a <NEEDED_FILES> \
	/var/lib/interchange/foundation_CVS
!endblock

H3:Install and test the new catalog

N:Now lets move the old {{F:foundation}} out of the way and put the new
{{F:foundation_CVS}} in its place. 

!block example;
cd /var/lib/interchange/
mv foundation foundation_old
mv foundation_CVS foundation
!endblock

N:Now, link up the CVS images for use by Apache.

!block example;
cd /var/www/html/foundation/
mv images images_old
ln -s /var/lib/interchange/foundation/images images
!endblock

N:Now, you should have a working catalog again.  To make sure, start up
Interchange and test the site with your browser. 

H2:Testing manual CVS updates on Interchange catalogs

N:Next, lets again update the checkout we made a while back before importing
our catalog.  (Alternatively, one could use a visual CVS client detailed above). 

!block example;
cd ~/src
cvs -q up -d foundation	# -q for quiet, -d for directory prune/update
!endblock

N:Additionally, you might test making a change to one of your checked-out
source files, saving it, then committing it. 

!block example;
{{B:index.html:}}
<!--this is a test comment at the top of index.html-->
!endblock

N:Now commit the change

E:cvs commit index.html

N:Your changed version will now be resident in the repository.  Again, CVS
documentation is in the {{SECT:Resources}} Appendix.   
 
N:This time, we can allow the changes to take effect on the code being used by
Interchange to serve pages. To do so, one must run a {{EX:cvs update}} on the
catalog directory:  

!block example;
cd /var/lib/interchange/foundation
cvs -q up -d	#up is the shortened version of "update" 
!endblock

N:That should notify you of the new version it downloaded with something like:

U pages/index.html

N:You may also get something like the following:

!block example;
M catalog.cfg
M etc/status.foundation
M ...
? orders/000001
? ...
!endblock

N:The {{EX:?}} lines in the above example mean that the CVS server has never 
heard of the listed directories or files (they are in your local source dir but 
not in the CVS source dir).  It is harmless, but sometimes annoying, and can be
taken care of with CVSIGNORE.

N:The {{EX:M}} means that the file has been modified on your local copy, and is
out of sync with the remote CVS version (e.g. when Interchange runs it updates
{{F:etc/status.foundation}}).  Normally this is corrected by uploading your
"modified" version to the server, but in this case, the modification was done
by Interchange instead of the programmer, and wasn't meant to be committed back
to the CVS repository.  See {{SECT:CVSIGNORE}}.  

N:Now, check to make sure that your change has taken effect by refreshing the
homepage on the site.  To see the comment, use {{EX:View->Page Source}} or
whatever the relevant command for your browser is.  

N:At this point, its obvious that it would be time consuming to manually run
'cvs up' every time you make a change to the source code, so the next step is
to setup CVS to automatically update the catalog whenever you commit something
to CVS.   

H2:Automatic updates on commit

N:Start by modifying $CVSROOT/CVSROOT/loginfo

!block example;
^foundation	(date; cat; ( \
	sleep 1; cd /var/lib/interchange/foundation; cvs -q update -d \
	) &) >> $CVSROOT/CVSROOT/updatelog 2>&1
!endblock

N:The first line tells CVS that for every commit on modules that start with
"foundation" (notice the regular expression {{EX:"^foundation"}}), it will run
{{EX:cvs update}} on the given catalog directory in the background.  It is
important that it is executed in a forked shell (notice the {{EX:"&"}}) after
{{EX:sleep}}'ing for 1 second, because otherwise you may run into contention
issues that can cause file locking problems.  The 1 second timing used above
works fine for me, but a longer pause may be necessary for slower computers
(you'll know if you get errors about "file locked by user").  See the CVS
documentation in the {{SECT:Resources}} Appendix for more details.        

H2:Automatic e-mail on commit

N:Often it is very helpful to have a commit mailing list that keeps developers
up-to-date on every commit happening to the CVS.  Perform these steps:

 * Download syncmail
 

!block example
mkdir ~/src; cd ~/src
cvs co CVSROOT
cd CVSROOT
cvs up
wget \
	http://www.icdevgroup.org/~danb/log_accum.pl \
	http://www.icdevgroup.org/~danb/mailout \
	#done.
chmod u+x log_accum.pl mailout
cvs add log_accum.pl mailout
touch updatelog
cvs add updatelog
cat >>checkoutlist <<EOF
log_accum.pl
mailout
updatelog
EOF
# Fix Permissions for updatelog
cd $CVSROOT/CVSROOT
chmod g+w *
echo 'ALL $CVSROOT/CVSROOT/log_accum.pl %s' >> loginfo
cvs commit -m "Automatic E-mail" checkoutlist loginfo ${FN} 
!endblock

As root, you must setup the "cvs-log" alias to go to the correct e-mail address(es).

!block example
echo 'cvs-log: email_one@yahoo.com,email_two@yahoo.com' >> /etc/aliases
newaliases
!endblock

See {{SECT:Mailserver for CVS updates}}.

Here is what a sample e-mail looks like:   

!block example;
User:      danb
Date:      2003-01-16 23:40:47 GMT
Modified:  pages    index.html
Log:
Testing...


Revision  Changes    Path
1.10      +1 -8      hoopstore/pages/index.html



rev 1.10, prev_rev 1.9
Index: index.html
===================================================================
RCS file: /home/interch/rep/hoopstore/pages/index.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- index.html  16 Jan 2003 22:47:55 -0000      1.9
+++ index.html  16 Jan 2003 23:40:47 -0000      1.10
@@ -31,7 +31,7 @@
   [control-set]
     [component]none[/component]
   [/control-set]
- 
+
 
   [control reset=1]
 
@@ -51,10 +51,3 @@
 <!-- END CONTENT -->
 
 @_LEFTRIGHT_BOTTOM_@
-
-
!endblock

N:Now you have a working CVS development system.  At this point it may be
valuable to learn more about CVS the client tools that you are using.  

H1:The two track model: development and live catalogs

N:It is often very valuable to have a two-track development model that separates 
the classes of work into separate timing and decision categories.  Some use 
"staging" and "production" terminology, others prefer "unstable" and "stable", 
"beta" and "release", or "development" and "live".  

N:The easiest starting point for two-track development is to just use two
completely separate CVS modules and catalogs.  This can make a lot of sense for
many situations, for example when the next revision of the site will be so
different that it is for all practical purposes starting from ground zero.   

N:A slightly more complicated solution is to use the CVS branches feature.  It
is more difficult to set up, but can be rewarding when used correctly. 

H2:When to branch

N:The first decision is when to branch the source code.  For websites, this can
sometimes be an easy decision like "first went live", or "site-wide overhaul",
etc.    

H2:Which way to branch

N:There are many different ways to branch source code.  What seems to be the 
most common method is to use the "trunk", which is the HEAD tag to CVS as the 
development version, and then make a branch when a stable release is to be made.    

N:That model doesn't fit my development style at the current time, so I use the
HEAD default branch as my stable live version, and use other tags (like DEV1
and DEV_REALLY_UNSTABLE) for my development branch.  

N:You may find that you are merging (or "folding") most or all of your
development ranch back into your stable branch frequently.  This is because
unlike traditional programming where products are launched every two or three
years with new features, web sites often have little fixes and new features
added every day or every few weeks, with new "releases" happening more often
than traditional software development (though not all web sites follow that
trend).  The flexibility is there to branch the source for quite some time to
work on a very complex feature or complete redesign before bringing it to the
live site, as well as the flexibility for day-to-day updates.        

H2:Performing the branch

N:To perform the branch use the {{EX:cvs tag -b <BRANCH NAME>}} command.  For
example: 

!block example;
cvs tag -b DEV1
!endblock

N:Remember that this does not change your locally checked out working directory
to the new tag automatically, it only creates the branch within the CVS
repository.  

H2:Setup the development catalog

N:Now we have a branch in CVS, but we need to tie it to something in the real
world, namely, an Interchange catalog. 

H3:Importing the catalog

N:Like we did in {{SECT:Integrating CVS with Interchange}}, you must make
another copy of your catalog for use as the development version.  Some would
like to keep the orders/, logs/, and other directories the same, but I prefer
to start with a clean slate, especially since I don't plan on having any
customers visit the development site.  (In fact, you can restrict who can
access the development URL using the Apache {{EX:<Directory> allow from...}}
directive).      

H4:Checkout source code

!block example;
cd /var/lib/interchange
cvs co -d foundation_dev foundation
!endblock

H4:Copy any other needed directories to complete the catalog

N:Depending on how complete your catalog is in CVS, you may need to create or
copy directories/files. 

!block example;
cd /var/lib/interchange/foundation
cp -a catalog.cfg orders/*   \
	/var/lib/interchange/foundation_dev
!endblock

Note:A lot of the following steps are performed by the
/usr/local/interchange/bin/makecat script, but here is how to do it manually: 

H3:Setting up a separate database

N:Most often, I find it profitable to make use of a second database for the
development catalog, rather than having both catalogs reference the same
database (especially if the first catalog is live).  

H4:Create a second database

N:Use the means of your database platform to create a separate database.  For
example, PostgreSQL users might do something like: 

{{EX:createdb foundation_dev}}

H4:Populate the database

N:You can rely on the catalogs internal products/*.txt data to generate the
database tables and populate them, or you can export another catalog's database
and import it for the development catalog, like the example below for
PostgreSQL users.   

!block example;
pg_dump foundation  > ~/foundation.dump
psql foundation_dev < ~/foundation.dump
!endblock

H3:Copy the catalog support files

!block example;
#Must be root
su - root

#Copy HTML
cd /var/www/html/
cp -a foundation foundation_dev

#Copy CGI
cd /var/www/cgi-bin
cp -a foundation foundation_dev
!endblock

H3:Configure the Interchange daemon

N:Perform the necessary modifications to {{F:interchange.cfg}}.  For example:

!block example;
{{B:/usr/local/interchange/interchange.cfg:}}
Catalog found     /var/lib/interchange/foundation     /cgi-bin/foundation
Catalog found_dev /var/lib/interchange/foundation_dev /cgi-bin/foundation_dev
!endblock

H3:Configure the catalog specifics

N:The development catalog will differ at least a little bit from the standard
catalog, such as in the CGI_URL and database parameters.  I recommend using a separate "local" configuration file to hold the separate values, such as {{F:config/local.cfg}}, and then include it from catalog.cfg.

!block example;
{{B:/var/lib/interchange/config/local.cfg:}}
Variable CGI_URL   /cgi-bin/foundation_dev
Variable IMAGE_DIR /foundation_dev/images
!endblock

N:Now you can restart Interchange to make your changes take effect.

H2:Splitting updates on commit by tag

N:Setup CVS so that when you commit to the DEV1 branch, only the development
({{EX:foundation_dev}}) catalog will be updated.  And when you commit with no
tags (HEAD branch), the live ({{EX:foundation}}) catalog will be updated.  Here
is an example {{F:loginfo}}.  The {{EX:-r <tag>}} may be used just in case your
environment is such that the tags may be changed by other sources.    

!block example;
{{B:$CVSROOT/CVSROOT/loginfo:}}
foundation   \
	(date; cat; ( \
	sleep 1; cd /var/lib/interchange/foundation_dev; cvs -q up -d; \
	cd /var/lib/interchange/foundation; \
	cvs -q up -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1
ALL     /usr/bin/cvs-log     $CVSROOT/CVSROOT/commitlog $USER "%{sVv}"
!endblock

H2:Using new branches

N:To use your new branch, checkout a working copy of the source with the
correct tag specified.  For example: 

!block example;
cvs co -P -r DEV1
!endblock

N:Then make change to one of the files, and commit it.  The change should show
on your development catalog, but not your live catalog. 

H2:Merging

N:When you want to merge a change that you have made on your development branch
into your stable branch, there are many ways that you can do it.  One would be
to :  

- Make a change in the development branch (DEV1) and commit it.
- Copy the development-tagged file to a temporary name
- Update to the live version (HEAD)
- Overwrite the live (HEAD) version of the file with your temporary one
- Commit the result
- Update back to the development version (DEV1)

N:I do the above so often that I have written a Tcl script for WinCVS that will
automatically perform the above steps.  And similar shell scripts can probably
be easily written to match your development environment.  

N:The above seems to be the easiest way, to me.  However, there are other
alternatives detailed in the CVS manual in chapter 5, "Branching and merging",
that I highly recommend for reading.  One method involves specifying the last
version that has already been merged into the live branch using a specific
version number, date, relative time, or special purpose tag.    

H1:Tools of the trade

N:This is the productivity tips section, which will hopefully help you to be
able to get more done in less time. 

H2:Workstation Interchange installation

N:Not all developers work on Linux workstations, many use Apples (graphics
designers and HTML gurus tend to, I've found), and many use Windows.  This
means that many developers have the extra step of uploading their changes to a
Unix server where Interchange is running in order to see their changes.   

N:The remedy to that is to setup an Interchange server on your workstation, or
any location that has direct access to the CVS source files.  I'll explain: 

N:The Interchange server that runs where the CVS server is (that we setup 
earlier) can be seen as the gathering point for all the developers.  However, 
each developer may run as many Interchange daemons as he/she requires in a local
context for the purpose of seeing the changes made before uploading them via 
CVS.     

N:For example, Bob could setup another Interchange catalog on the same server as
 the CVS, (e.g. foundation-bob).  To get direct access to those files (rather 
 than FTP), Bob could use NFS mounts (if Bob's workstation is Linux) or SMB 
 mounts using Samba if his workstation is a Windows variant.  Any way that Bob 
 can get direct access to the files will save him some time (by cutting out the 
 "upload" from the "edit->upload->test" development cycle).  One could even use 
 VMware to run a Linux server on your Windows workstation.    

Note: You can now use the cygwin compatibility confirmed in Interchange
versions 4.7.6 and above to run Interchange right on your Windows workstation. 

N:The result will be that you can modify the files with your favorite text 
editor and see the results immediately through your local catalog.  Setting up 
the catalog initially is quite easy.  Just follow the same steps used to setup 
the CVS catalog.  Which is:    

 * Checkout from CVS into a new CVS catalog directory and link the images/
directory.

 * Make localized configuration modifications.  I recommend creating a {{F:config/local.cfg}} file and then {{EX:include}} it at the top of catalog.cfg, with the contents of:

!block example
Variable CGI_URL	/cgi-bin/foundation
Variable SERVER	testserver
Variable SECURE_ENABLE	0
Variable IMAGE_DIR	/foundation/images
!endblock

*Restart Interchange.

N:You may need to remove all *.sql files from the products directory, to create all of the database files again.  Additionally, you may need to create the database, username/password for your database again as well.

N:You will need to recreate any symbolic links that previously existed, such as templates/default -> templates/foundation

N:Another thing that you might have noticed at this point is all the files that
are modified locally by the Interchange daemon will report ? or M when you run
an update.  To fix this, see {{SECT:CVSIGNORE}}.
 
H2:CVSIGNORE

N: On the heals of a workstation installation is the requirement to setup CVSIGNORE.  For all files that change, but you want to ignore (such as {{F:etc/foundation.status}}), create an entry in the .cvsignore file in that directory.  Note that the file must be removed from the cvs repository before it will work.

Here is a script that will create some sample files:

!block example

cat >.cvsignore <<EOF
error.log
*.structure
timed
tmp
EOF

cat >etc/.cvsignore <<EOF
status.*
*.counter
*.number
*.recordnumber
EOF

cat >products/.cvsignore <<EOF
*.lnk
*.sql
*.autonumber
*.[1-9]*
*.csv.numeric
*.name
*.sort
*.txt.*
EOF


echo "local.cfg" > config/.cvsignore
echo "*" > backup/.cvsignore
echo "*" > logs/.cvsignore
echo "*" > orders/.cvsignore
echo "*" > session/.cvsignore
echo "*" > upload/.cvsignore
echo "*" > tmp/.cvsignore

cvs add \
	.cvsignore \
	etc/.cvsignore \
	products/.cvsignore \
	config/.cvsignore \
	backup/.cvsignore \
	logs/.cvsignore \
	orders/.cvsignore \
	session/.cvsignore \
	upload/.cvsignore \
	tmp/.cvsignore \
	#done.


!endblock

H2:Mailserver for CVS updates

N:An easy alternative to setting up a mailserver is to merely alias the addresses that you would like updated.  If you don't have many users following your commit list, it is recommended.  In {{F:/etc/aliases}}, merely put:

E: cvs-log:	address_one@yahoo.com,address_two@yahoo.com,address_three@yahoo.com

Then run {{EX: newaliases}} and your "mini" mailing list will be all setup. 

N:To setup a mailserver for CVS updates, first download and install Mailman.
For RPM-based systems, check on rpmfind.net for a precompiled binary package.  

N:After installing, read the following information about Mailman and what needs
to be done after installation (taken from the RPM meta data): 

N:"Mailman is software to help manage email discussion lists, much like
Majordomo and Smartmail. Unlike most similar products, Mailman gives
each mailing list a web page, and allows users to subscribe,
unsubscribe, etc. over the web. Even the list manager can administer
his or her list entirely from the web. Mailman also integrates most
things people want to do with mailing lists, including archiving, mail
<-> news gateways, and so on.

N:When the package has finished installing, you will need to:

* Run {{F:/var/mailman/bin/mmsitepass}}
  to set the Mailman administrator password.
* Edit {{F:/var/mailman/Mailman/mm_cfg.py}}
  to customize Mailman's configuration for your site.
* Modify the sendmail configuration to ensure that it is running and
  accepting connections from the outside world (to ensure that it runs,
  set "DAEMON=yes" in /etc/sysconfig/sendmail, ensuring that it accepts
  connections from the outside world may require modifying
  /etc/mail/sendmail.mc and regenerating sendmail.cf), and
* Add these lines:
!block example;
  ScriptAlias /mailman/ /var/mailman/cgi-bin/
  Alias /pipermail/ /var/mailman/archives/public/
  <Directory /var/mailman/archives>
    Options +FollowSymlinks
  </Directory>
!endblock
  to {{F:/etc/httpd/conf/httpd.conf}} to configure your web server.

N:Users upgrading from previous releases of this package may need to
move their data or adjust the configuration files to point to the
locations where their data is."

N:Then run {{EX:/var/mailman/bin/newlist}} and follow the directions from there.  

H2:Locally mapped source code for a network IC server

N:This is useful mostly to Windows users, since Linux users can just as easily 
run IC daemons on their own workstation as they can a separate server.  

N:The idea is to have the IC server use its own files and directories for things
 that won't be edited and modified locally, but reference a Samba directory or 
 NFS directory for things that will (such as {{F:pages/}}, {{F:templates/}}, 
 etc.).

H3:Mount the Samba or NFS directory

N:{{EX:smbmount <...>}} or {{EX:mount -t nfsfs <...>}}

N:The following script uses two directories (source and destination) to create
symlinks for the commonly modified source directories of Interchange. 

!block example;
export S=/mnt/nfs/foundation
export D=/var/lib/interchange/foundation
F=db; ln -s $S/$F $D/$F
F=dbconf; ln -s $S/$F $D/$F
F=etc; ln -s $S/$F $D/$F
F=images; ln -s $S/$F $D/$F
F=pages; ln -s $S/$F $D/$F
F=special_pages; ln -s $S/$F $D/$F
F=templates; ln -s $S/$F $D/$F
!endblock

N:This will leave you with a working catalog that can be quickly modified
(since your editor can access the local copy), while Interchange has to do the
work of going over the SMB or NFS connection.  

H2:jEdit - a good editor with Interchange/HTML/Perl colorization and CVS

N:I have been quite impressed with jEdit ({{URL:http://www.jedit.org}}, and open
 source editor that is written in Java and runs on most platforms.  

N:I use the interchange.xml language definition written by Chris Jesseman
{{EMAIL:chris@sitemajic.net}}, which is available from
{{URL:http://www.sitemajic.net/jedit/}}.  With this, jEdit automatically colors
HTML, Perl, AND many Interchange tags very intelligently.   

N:Further, jEdit has a CVS plugin, written by Ben Sarsgard
{{EMAIL:bsarsgard@vmtllc.com}}, and available at:
{{URL:http://www.vmtllc.com/~bsarsgard/jedit.html}}.  This plugin allows you to
diff, update, and commit right from the editor.   

H2:Separate servers for development and live catalogs

N:If you have the luxury of separate server hardware for the development and
live catalogs, you might find the following utility helpful: 

*CVSviaFTP ({{URL:http://www.cvshome.org/dev/addoncvsftp.html}}) - from the CVS
Add-ons page ({{URL:http://www.cvshome.org/dev/addons.html}}). 

N:It allows one to have a given CVS module automatically publish each update to
an FTP server, which could serve as the live server.  Or one could could use it
if your CVS installation is only local and you could use it to upload your
changes to your production server.   

A1:Credits

*{{B:Jon Jensen}}: Thanks for helping me get going on the SDF format already 
used by the Interchange documentation, and fixing some SDF syntax errors.  
*{{B:Mike Heins & all who have contributed to the success of Interchange}}:
Thanks for following the Way Of The Source, for quality programming, and for
helping to making IC something to write about.  
*Thanks to the countless others who have written the CVS documentation that is
available online, which was my only source for learning CVS. 

A1:Document history

*May 2001.  Conceived and written by Dan Browning.
*July 19, 2001.  First draft complete, first public release.
*April 12, 2002.  Minor typographical edit.
*June 8, 2002.  Minor updates.

A1:Resources

A2:CVS Documentation

N:Here are some resources for learning more about CVS.  I have ranked them by
the order of usefulness, which is of course, objective.

*Karl Fogel's CVS book {{URL:http://cvsbook.red-bean.com/}}
*The official CVS manual {{URL:http://www.cvshome.org/docs/manual/}}
*The official CVS FAQ {{URL:http://faq.cvshome.org/}}
*The official CVS homepage {{URL:http://www.cvshome.org}}
*Info-CVS mailing list {{URL:http://mail.gnu.org/mailman/listinfo/info-cvs}}
*CVS FAQ 2 {{URL:http://www.cs.utah.edu/dept/old/texinfo/cvs/FAQ.txt}}
*Sean Dreilinger's CVS Version Control for Web Site Projects {{URL:http://durak.org/cvswebsites/}}
*Pascal Molli's CVS reference site {{URL:http://www.loria.fr/~molli/cvs-index.html}}
*CVS Tutorial {{URL:http://cellworks.washington.edu/pub/docs/cvs/tutorial/cvs_tutorial_1.html}}
*CVS Tutorial 2 {{URL:http://www.csc.calpoly.edu/~dbutler/tutorials/winter96/cvs/}}
*Red Hat CVS pserver setup guide {{URL:http://www.michael-amorose.com/cvs/}}
*CVS Add-ons {{URL:http://www.cvshome.org/dev/addons.html}}

A2:CVS Server Software

*CVS RPM download (Red Hat Linux 7.1)  {{URL:ftp://speakeasy.rpmfind.net/linux/redhat/7.1/en/os/i386/RedHat/RPMS/cvs-1.11-3.i386.rpm}}

*Links to source tarball links can can be found at cvshome.org.

A2:CVS Client Software

N:There is a variety of client access methods for using CVS on your development
box. 

*CVSGUI is a great project that brings graphical clients to Linux, Windows, and
Mac at {{URL:http://www.cvsgui.org}}.  These also give you the same access to
all the command line cvs commands.  

*jCVS is a great cross-platform graphical CVS client available at
{{URL:http://www.jcvs.org}}. 

*jEdit is a great cross-platform text editor written in java, which not only
has a CVS module that allows you to commit (upload) files directly from the
editor, but also has a Interchange Tag Language (and Perl language)
colorizer/parser.  It is available from {{URL:http://www.jedit.org}}.   

Line:

N:Copyright 2002-2004 Interchange Development Group. Copyright 2001-2002 Dan Browning <dan.browning@kavod.com>. Freely redistributable under terms of the GNU General Public License.