Title: Using Version Control

Fundamentally version control is about being able to manage versions of the source code. This management includes the ability to reproduce identified versions of the source code, to query differences between versions and to allow the changes made between two versions to be applied to a third.

There are significant differences between version control systems in the way they implement these facilities - at their most primitive they do no more than record a sequence of changes to individual files, at their most sophisticated they also manage the addition and removal of source file, allow concurrent changes, automate the software build process, ensure regression tests succeed, enforce sign-off processes and create and distribute the resulting software.

While much of the following discussion is generic in nature it uses CVS as a specific example of a source code version control system. CVS is a free [GPL] version control system that falls between the primitive and sophisticated extremes identified above: as with much 'free' software it provides a basic set of version control features important to developers and does it well. It does not provide the additional process management features available in some commercial products (but there are separate tools for some of these tasks that integrate with CVS).

As an individual developer I want a version control system to manage the changes that I make without putting obstructions in the way of my making them. Ideally I just want to make changes to my working copy of the system and for any interaction of these with the shared development and/or release versions of the system to be resolved automatically. Within my working copy I'd like to be able to use the version control system to answer queries such as "what did I change this morning?" and to allow facilitate operations like "undo all my changes to this file" or "undo the changes I made last Friday afternoon (without losing any prior or subsequent changes)".

Some version control systems only allow a single developer to a file at a time. In practice, when version control prevents a developer from making a necessary change they bypass the version control system in order to get work done. (By changing local copies of files followed later by manual integration of their changes.) This loses potential benefits of version control, can be error prone, and risks scenarios where neither of two developers can check in their changes without first updating a file "owned" by the other.

Whether working as an individual developer, in quality assurance, or as a release manager I want to be in control of when the changes other people make impact my working copy. Ideally the version control system will allow me to choose when to update my working copy, to select specific updates and to ensure that the all the changes relating to the update are applied.

A problem that occurs with some version control systems is that they may require me to "check out" a specific version of a file - e.g. to add a method I may need to get the latest version, and this version may not be consistent with other files within my working copy.

Reworking these requirements as a checklist:

The key idea to understand when working with CVS is that the version in the repository is the important one. The user issues to update the working copy or to apply changes from the working copy to the repository. This implies that in order to track changes by individual developers separately (as described above) it is necessary for each developer to maintain a separate version of a project within CVS. The mechanism that CVS provides for this is "branching" - each branch is an independent version of the project.

Working on a branch you allows CVS to track your changes for you whilst being isolated from any other work being done at the same time. It also means your changes don't affect anyone else and you are not affected by them (unless or until you intentionally merge the changes).

Figure 1. Basic Branching

Unless the version within the repository is updated to match the working copy on a regular basis developers won't be able to use the CVS facilities to manage changes, so it is a good habit to check in changes on a regular basis - after each cycle of update, compile and test is about right (i.e. several times a day). Remember, these check-ins only affect the current branch.

The CVS branching mechanism also provides a convenient way to group changes relating to a logical update - by creating a branch for each such update allows the changes to be identified as those that occur on that branch. On completion of a logical update several things need to happen: the change must be made available for QA, the change must be integrated into the principle development version, and into any appropriate release version - this is discussed further below.

The QA and release functions have similar needs to control change (but in these cases source updates should always be applied by the version control system - not by changing the source code). For this reason they too should work on branches - although in this case the branch will, potentially, be 'handed on' from QA to release.

The project we are going to consider is the development and maintenance of an application that is maintained over a series of releases - the series of releases open ended. (I've used CVS with up to a dozen developers on projects up to a million lines of code, I've heard reports of much larger projects.)

In this project the main branch (known as the trunk) is the development integration branch. Most other branches are split off this and have a limited lifetime. In particular, all development of new features is done on branches that are then merged back into the trunk.

At a given moment there are potentially two other main branches - a "Release" branch undergoing "QA" and a "Release" branch corresponding to released software. The release process is as follows:

Ensure that all bugfixes (e.g. to QA and release branches) have been merged back into the trunk.

Build the trunk and run regression tests.

Create a new Release by branching from the trunk. (Development continues on the trunk.)

Run the full test suite against the new branch. (If problems are found they may be corrected on this branch - or on branches that are merged back into it.)

Once QA "passes" the new release, any bugfixes that were made to achieve this pass are scheduled to be merged back into the trunk.

(Eventually) retire the old Release branch. (If problems are found in the field they may be corrected on this branch - and scheduled for merging back into the trunk.)

Figure 2. Branches during the project lifecycle