16 April 2005 - 1:01CVS Revision Management on Multiple Projects With Minor Differences

There are times when you will have a project that multiple clients will be using and some of them may have permanent minor changes that need to remain even if bug fixes or code updates are made. Initially branches in CVS seem to be able to fulfill these needs, but the examples that the CVS documentation used had branches to separate to its own entity. Basically branches were only used as a bug fix branch for a particular early version. This way the bug fixes from the branch could be applied to the HEAD. I have found a relatively simple way to synchronize multiple clients each having their own changes using a single common HEAD as the generic project. Current development can be made against the head and when major releases are tagged, the release can be propagated to the clients at their own speed. The only requirement is that certain standards must be followed in order to be take advantage of the ability, but a certain amount of standardization should be performed anyway.

Problem

First you should be familiar with CVS branching and tagging. Consult the info page that comes with the CVS distribution.

In this example I’ll use two clients A and B each using a slightly custom version of the HEAD. A and B need to continue to update their own custom code slightly while being able to receive major code updates in the HEAD. Their modifications should be easily transferred over without remembering the specific modifications. Think of a revision tree similar to the following:

br_a       ----------------------
          /
HEAD ----------------------------
                 \
br_b              ---------------

Time --------->

Solution

First, I’ll come up with the naming rules:

• A new client specific branch for a client named “C” will have a new branch created for them named br-c.
• Any tags located on the branch will contain the br-c prefix.
• Tags should not mix files from different branches.
• Releases will be labeled rel-X, fixes rel-X-Y, where the initial release is rel-1 and further releases are numbered sequentially. They do not need to correspond to the physical release number of the project. Any branch prefixes apply to this also, ex: br-c-rel-X-Y.
• when a branch gets the new changes from the head release merged to the branch, the head versions need to get tagged with a merged-br-c.
• (optional) branches will only be created off of a version tag.

The main ability to merge the HEAD changes comes from the merged-br-c tag. This tag is very important since it marks the last time on the head branch that changes were merged. This way the cvs update command with two -j flags will find the difference between that old merged-br-c tag on the HEAD and the current release you’re trying to merge with.

Assuming now that we’ve had several releases, here is an example of the tree structure:

        rel-1  rel-2      rel-3
br_a       ----------------------
          /
head ----|------|----------|-----
                 \
br_b              ---------------

Here are the commands associated with managing client specific branches.

To create a branch for a new client c from the head trunk (or optional release):

cvs rtag -b (-r rel-X) br-c module
cvs rtag (-r rel-X) merged-br-c module

To merge the differences in the HEAD project to a client branch:

(this is only needed if module not checked out yet)
cvs checkout -r br-c module
cd module

(the next will actually merge the changes)
cvs update -r br-c -j merged-br-c -j rel-X

(fix conflicts, check merges)
cvs commit -m "Merged from rel-X"
cvs rtag -r rel-X -F merged-br-c module

When you have hit a milestone in the HEAD branch, you should tag it as a release. Make sure you’re in the HEAD.

(While in the module with the correct versions checked out.)
cvs tag rel-X
(Anywhere, tags HEAD.)
cvs rtag rel-X module

WARNING: Make sure that you know what branch you are on!!! If you are at all unclear make sure you use the cvs status and cvs update -A commands frequently to make sure you are tagging the correct code.

Conclusion

Although CVS branching and tagging can be fairly complex when first learning, it is a valuable tool when dealing with multiple versions of a large project. By following these recommendations and commands, you can successfully manage several blocks of client code in branches while maintaining them from the central HEAD.