Configuration Control Procedures for ABLE

Andrew Kompanek

Introduction

All of the ABLE source code and documentation files are managed using CVS (Concurrent Version System). CVS is a front-end to an older tool called RCS and provides a higher level interface to that program and some features not supported directly by it. In a nutshell, it is a revision control system that allows multiple developers to work concurrently on the same code. It has mechanisms to resolve conflicting changes and also automatically tracks changes and maintains a database of revisions.

With CVS it is possible to mark different versions of the code as checkpoints so that it's easy to revert back to an older version of the system or some subset of the system. These versions might correspond to released versions of the system or simply checkpoints before large changes so that if need be one can revert back to old code for whatever reason. There are also some mechanisms for supporting multiple development paths.

This document describes some of the basics of CVS as well as outlining our particular setup. Some details still need to be worked out in terms of how we'll be managing revisions but the basics will be the same.

The Repository

All of the files for the able project live in a central CVS repository. This is simply a central location which contains incremental versions of the system and the information that CVS needs to manage those files. For the most part only the repository maintainer needs to anything about details. You do need to set an environment variable to point toward the repository. If you're using a csh derivative that's setenv CVSROOT /afs/cs/project/able/sunos/cvs. Alternatively simply source /afs/cs/project/able/bin/ablesetup.csh. which is what you should be doing anyway since this will have other useful setup goodies in it. This should probably be done in your .login at startup.

In repository code is organized into modules which are really just top-level directories of files. A listing of all of the current modules and their contents will also be maintained (with a link here eventually). Currently, the major modules for ABLE are:

ui: This contains the main user interface code and defines the generic style. New styles are derived from the code in this directory.
fcl: This is the code that defines FCL. It includes C sources that provide persistent database access and the Tcl code which defines the higher level object system.
doc: Currently, most of the documentation for the project is here but I believe that there is documentation that is not currently in the repository.
unix-pf: The additional code for the Unix Pipe Filter style. Includes a main.tcl for starting the pipe filter environment.
pf: Some code used by unix-pf. I think that unix-pf is derived from classes here. Currently, this is not a stand-alone style.
msg: The code for yet another style.
cr: The code for the change request tool.

Checking out and working with system

Working with repository involves a number of steps. First you need to checkout a copy of the modules which you'll be working with. You'll then periodically commit your version. In general you'll want to commit when you reach stable points in development and before you undertake something new that might break the system. The other thing you'll need do is periodically update from the repository -- incorporate others changes into your code. Create a directory for yourself to work in:

% mkdir /afs/cs/project/able/sunos/me

You can now check out a copy of the module with:

% cvs checkout <module name>

This will create a directory called me/<module name> Once you make a change you can commit it back to the repository with

% cvs commit [module or filename in module]

At this point CVS will pop an editor for you (the editor is defined in the environment variable EDITOR) to type in a log message, such as "broke the system beyond repair." Then you'll get several messages that just mean everything is going OK.

Note that a commit will only effect files that have been added using cvs add. This is handy because it allows you to keep temporary files around your local collection without being bothered about them when you commit.

In order to add a new file to the repository after creating the file in the directory use:

% cvs add <somefile>

You then commit this file to make it part of the repository

To update from the repository use:

% cvs update

Without a file name argument, this command lists the files in the local collection that you have modified, and also checks for files in the master collection that others have modified, but you have not. It it finds any of these, it updates your local copy. Each file that has changed in some way is listed with a single character marker. If you've given it an argument this will only occur for your file. The markers have the following meanings:

U: The file was updated in the master collection and your local copy has been updated.
A: You added the file to your local collection, but have not yet committed the change to the master collection.
R: You have removed the file from your local collection, but have not committed the change.
M: You have updated the file in your local collection, but have not yet committed the change.
C: The file has been updated both by you and in the master collection, and the updates conflict. CVS will ask you to take steps to figure out how to merge the two sets of changes. The regions of conflict will be marked as text added to the file that contains the conflict.
?: The file is unknown which means it isn't in the repository.

These messages will also occur if you commit without having done an update.

Tagging and CVS Releases

The explanation above assumes you're working with what amounts to to the most recent, main development version of the system. CVS lets you maintain different versions with a mechanism called branching. There is also a way to explicitly mark a certain version of the repository -- that is mark all the files you've currently checked either collectively or some subset. These give you an easy way to refer back. This will be text based upon Pete Psu's writeup and incorporate our new scheme for version management -- i.e., what the branching. Should start a picture like Pete's of how branching works in general. Also explanation of revision numbers needs to be here..

I may also create some aliases that take care of the tagging automatically if this looks like it will make things easier to manage. Also talk about the "build version" that we'll maintain on AFS... still need to work out the details here.

Adding a module

At some point you may want to create a new module. In order to keep track of big development decisions, I think it's probably a good idea to let me (kompanek@cs) know you want a new module and I'll create it so that you can check it. I think this will reduce the chaos somewhat. If you realy want to know how this works there's info. in Pete's old page.

Additional Info.

For information about how to do other things, such as checking change logs, reverting to the version of a module stored in the master collection and aborting all your current changes, and other things, look at the CVS man page. Summary information can also be found by typing cvs help.

There is a also a html'ized CVS Information page that's full of stuff you might want to take a look at and has neat fish icons to boot. I'll stick a more official pointer to the FAQ here (which I'll grab so we have it around), too.