Version management in The Meta-Environment

One can use a version management system in different ways. This document describes our methods concerning checkout, commits, branching, and tool support. The standard version control system is Subversion. The reader of this text is therefore expected to understand Subversion concepts:

The following links provide ample documentation on these subjects:

The Meta-Environment development team has two overall version management goals:

The version management policies and mechanisms described here, were chosen specifically to support these two goals.

The Meta-Environment consists of between 40 and 60 packages. These packages are managed using the Subversion version management system, stored in a single repositories located at:

svn+ssh://svn.cwi.nl/ To manage packages, the developers use the Subversion trunk, branch, and tags concepts. Since every package is individually version-managed, every package has its own trunk, zero or more branches, and zero or more tags. To achieve the first goal, the version of the code on the trunk should be kept stable, that is, the trunk should always store a reasonably up-to-date version of the package of production quality. It is the responsibility of every developer not to "break the code" on the trunk. The GLT development team distinguishes two types of changes:

Low-impact changes are trivial changes, such as the correction of typo's, and can be commit directly to the trunk. High-impact changes are basically all other, non-trivial changes. Since non-trivial changes threaten the stability of the code and the code on the trunk has to remain stable, all non-trivial changes require some form of consultation, peer review, and testing before being integrated into the trunk. The use of branches facilitates these activities since they allow version management for these changes, such as intermediate commits and rollbacks, independent of code on the trunk. Branches also allow version management for experiments, even if these experiments will not be integrated into the trunk, thus facilitating the second goal. The GLT team also uses a separate form of branches, called release branches, that facilitate maintenance on previously released code. As a consequence, the GLT team recognizes the following four types of branches:

On May 12th 2006, we have migrated the GLT modules from two CVS repositories, located at CWI and INRIA, to a single Subversion repository, located at CWI. Because of this migration, the cvsmerge script has lost its purpose. Instead you should use the SvnMerge script ("svnmerge") provided with the Subversion source.

To protect the stability of the trunk, a developer should always create a branch for an intended change, unless he is sure the change is trivial. When the development effort has resulted in stable code on the branch, the changes can be integrated (merged) into the trunk. The trunk should thus be considered the "integration branch" for the next release. This way of working is described by the mainline and task-branch SCM patterns. To prevent developmental and experimental branches from diverging (too much) from the trunk, developers should use the SvnMerge script to incorporate (merge) concurrent changes on the trunk into their branch. By using the script to stay up-to-date, merging changes back into the trunk becomes much easier because the process of resolving merge conflicts is spread over time.

A second source of branches is the release process. Every time a package is released, a branch is created for this release. All bug fixes for the released package are performed on this branch, and when desired foreward ported (e.g., merged) to the trunk. Release branches are never merged with the trunk. The process of forward porting changes on the release branch to the trunk is NOT supported by the SvnMerge script.

Each package has a ChangeLog file in its root directory that records all (important) changes to the package. The ChangeLog file consists of entries that provide a description of the change, including the date of the change, and that are sorted last change first. This change information can then be used, for instance, during debugging. When working on a branch, however, recording changes in the ChangeLog file requires special attention. The problem with the ChangeLog file occurs when changes (and their entries) are imported from the trunk. Since these changes have occured concurrently on the trunk and other branches, their dates overlap, and consequently their entries should be interleaved in the ChangeLog file. Interleaving the change information like this is, however, confusing. The solution to this problem is to use a separate ChangeLog file per branch (e.g., ChangeLog.<branch-name>) and record all changes on the branch in this file. This file is added to the branch and grows with every commit. Change entries from imported changes would still simply be added to the normal ChangeLog file. When work on the branch has completed and the changes can be integrated back into the trunk (i.e., "integration branch"), two extra steps are needed. The first step is that after the "svn merge" command (but before the associated commit), an entry is added to the ChangeLog file, which summarizes the whole ChangeLog.<branch-name>. The second step is the removal of the file ChangeLog.<branch-name>, that is, the file is not added/commited to the trunk.