Version Control

• Tcl procedures: /tcl/vc-defs
• User-accessible directory: none
• Site administrator directory: none
• Data model: none

The vc module provides an interface to the Concurrent Versions System (CVS).

The Big Picture

At this point we are all used to working collaboratively on site development, and to using CVS for managing the code base as the site is programmed. But what about modules that provide access to site content or software management tools? Do we give up version control in this case? Do we have to rewrite the machinery of a system like CVS? Absolutely not!

The vc module provides a simple interface to CVS that can be used by any module to add version control capabilities. It also provides procedures to obtain version control information for any file in the project, i.e. to display additional information in the page footer or for integration with bug tracking systems. Current modules that use vc include the package manager, the file manager, and the manual system.

API

vc_add path

vc_log path

vc_status path

vc_remove path

vc_commit path message

vc_update path

vc_checkout module path

This last command (equivalent to cvs co -d path module) is useful for grabbing a private copy of a file, e.g. to support simultaneous editors in a content-management system. The utility

vc_path_to_module path

will convert an absolute pathname into the corresponding CVS module that it was originally checked out of.

There are also a number of procs that simply grab information from CVS either by exec-ing the executable or by reading the appropriate version control information from the file system:

vc_fetch_repository path

vc_fetch_root path

vc_fetch_status path

vc_fetch_summary path

vc_fetch_date path

vc_fetch_revision path

An individual query can be relatively expensive, particularly if CVS has to go over the network to access information from a remote repository. Therefore, all information managed by the vc module is cached within the server based on the modification time of the corresponding file.

Setup

To use the vc module you will need to set the following parameters:

[ns/server/yourservername/acs/vc]
; Location of the CVS repository.  If the repository is on a remote
; host, you need to make sure that CVS can connect without being
; prompted for a password.
CVSROOT=/cvsweb
; Location of the CVS executable
CvsPath=/usr/local/bin/cvs

The parameter CVSROOT is exactly the same as the environment variable used by CVS. The parameter CvsPath specifies the location of the CVS executable. If you are running a chrooted server then the CVS executable must be located within the restricted path of the server.

Remote Repositories

The vc module will happily talk across the network to a remote repository, e.g. CVSROOT=hostname:/cvsweb/ will allow you to access the repository /cvsweb on hostname. The only connection methods currently supported are pserver and ext using secure shell as the connection agent (strongly recommended). For this to work the user nsadmin (or whatever user account the AOLserver binary runs as) must be able to connect to the repository host without being prompted for a password.

This is easy to set up and relatively secure using ssh with RSA authentication. We'll assume the server runs as nsadmin.

1. Login to the server host as nsadmin.
2. Run ssh-keygen with no passphrase to generate ~nsadmin/.ssh/identity.pub.
3. Copy ~nsadmin/.ssh/identity.pub to the repository host and append it to ~nsadmin/.ssh/authorized_keys.
4. Make sure the authorized_keys file has its permissions set to 400 and that /home/nsadmin is set to 755.
5. Try logging in from the server host to the repository host using ssh -v nsadmin@repository-host. If you fail to connect automatically, check the log output for some explanation as to why the authentication failed.
6. As a final test, try running cvs -n update from the top-level directory of your project while logged in as nsadmin to make sure that CVS can connect to the repository host correctly.

The most common problem is bad permissions. If your connection is failing then double-check the permissions on /home/nsadmin/ and /home/nsadmin/.ssh/authorized_keys.

chroot

If you're running a chrooted server there are two more steps. First, the cvs and ssh executables must be accessible in the restricted path. Second, you will need to copy the ssh configuration files into the correct chrooted location; if you're following the standard layout then:

cp /home/nsadmin/.ssh /webroot/aol30/.ssh

Once again, double-check the permissions as ssh is extremely picky about this.

Future Improvements

Might be nice to integerate with things like the ticket tracker or general comments on a page.

As written these procs are tied specifically to CVS, but they could be extended to work with RCS or SCCS repositories, or any other revision control system we might adopt in the future.