Version Control Design

by Ron Henderson

I. Essentials

II. Introduction

The VC application 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 associated with the project, e.g., to display additional information in the page footer or for integration with bug tracking systems.

III. Historical Considerations

None.

IV. Competitive Analysis

None.

VI. Data Model Discussion

None.

VII. Legal Transactions

None.

VIII. API

The VC application does not have any user pages, just a set of procedures that allow you to access the version control system. Every procedure takes the full pathname of a file to operate on. The public API consists of the following (all are direct analogies to the corresponding CVS command):
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 procedures 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

IX. User Interface

None.

X. Configuration/Parameters

To use the VC application 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 application 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.

XI. Acceptance Tests

The package includes an automated regression test. To run it you need to mount the package and access /vc/admin/tests/.

XII. Future Improvements/Areas of Likely Change

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.

XIII. Authors

ron@arsdigita.com