Tagging and branching

Tagging and branching are both ways of marking specific versions of a whole set of files as going together. Tagging is the simpler method. For example, if release 1.1 of a software package consisted of revision 1.15 of main.c, 1.4 of Makefile, etc., you could instead tag the whole tree at the time of release with a tag like RELEASE-1_1 and then later on, if you wanted exactly release 1.1, you could use cvs checkout with -r RELEASE-1_1 and pull exactly that release, with no subsequent changes.

Several of our CVS repositories, particularly the Kerberos repository, uses the tag PRODUCTION to mark the last known stable version. After new changes have been thoroughly tested and deployed, the PRODUCTION tag is moved to that version. This allows one to quickly fall back to the last known good state, without keeping around lots of tags for older releases. Use of this convention is encouraged.

In order to tag a tree of files, cd to the root level of your checked out copy and run cvs tag <tag> .. This will tag all the currently checked-out revisions with the given tag.

A branch is basically a stronger version than a tag. A tag applies to one particular revision, and can be moved to a later revision easily by just retagging the file. A branch, on the other hand, creates a fork in the repository; you can then commit changes to the mainline or to the branch, and changes committed in one place aren't reflected in the other.

There are three primary reasons to use branches. One is to branch off a stable version of a package before making major changes. The advantage to using a branch rather than just a release tag is that you can then continue to commit bug fixes to the stable branch, and perhaps even spin further minor releases from it, while you're doing major development on the mainline without hurting the stability of the stable branch.

Another is to do something experimental without impeding other development. One can branch the sources and then start making major changes, and other developers can continue working on the mainline sources without running into trouble from your potentially dangerous changes. Then, when the changes in the branch have stabilized, you can use the facilities of CVS to merge the changes from the branch back into the main code and automatically resolve most conflicts.

Finally, CVS's facilities for tracking vendor sources use branches, so that they can merge vendor's changes in new versions with local modifications. See import for more information on this.

It's unlikely that we'll have as much use for branches as for tags, except for managing vendor source. In general, our projects don't have as many developers and tend not to have separate stable and development tracks. But you never can tell; it might be useful down the road.

As mentioned in import, tags have to consist of letters, numbers, dashes, and underscores, and cannot contain periods. The standard way of representing the version 1.1 is 1_1. A good release tag is something like RELEASE-1_1 or PKGNAME-1_1 (or the PRODUCTION tag as described above). A good branch tag for a stable branch based on the 1.2 release would be STABLE-1_2. I generally use a convention of a word of some sort, a dash, and then the version number with periods replaced by underscores.