Resolving a 'sticky tag is not a valid branch in this CVS repository' error

The Drupal Contributions CVS repository has some very strict conventions on what branches and tags are considered valid. This is both to help prevent confusion, and to ensure smooth integration with the Drupal release system. If you try to do a cvs commit that uses an invalid branch or tag name ("sticky tag") you will receive an error message like this:

In this instance DRUPAL-6 is not a valid branch name. The correct branch name is DRUPAL-6--1.

The way to fix this error and proceed with your commit is to back up and follow the proper procedure for creating a correctly named branch. Let's say you've got a bunch of code in HEAD that's now ported to the 6.x core API and you want to make a new DRUPAL-6--1 stable branch for your contribution. The best way to add a new branch for your contribution is the following:

Note that you should not create a new branch by doing a cvs checkout of the modules directory, using the new branch name, like so:

and then adding files and committing them back again.

Why this happens

There are a series of validation scripts that run during every CVS operation which attempt to prevent contributors from creating invalid branches or tags. Most of these checks are done during the cvs tag command, which is the normal way to create both branches and tags.

Whenever you create a CVS checkout (local copy, workspace, whatever you what to call it) CVS remembers the specific branch or revision you checked out from with what's known as a Sticky tag. It's a little confusing that internally, CVS considers branches a special case of tags, and in the vast majority of cases, the sticky tag is really pointing to a branch. See the section on branches and tags in the CVS introduction if you're confused about the difference. Aside from the name, this "Sticky tag" functionality is normally great, since once you checkout from, say, the DRUPAL-6--1 branch, any further operations (diff, update, commit, etc) will all happen relative to the same branch.

If you checkout a workspace from a specific tag (not a branch), modify some files, and then try to commit the changes, you will get CVS's own sticky tag is not a branch error. In this case, the sticky tag is pointing to a tag (which can't change), and yet you're trying to modify the files that the tag is pointing to. You can only commit your changes to a branch, so your sticky tag must be pointing to a branch for CVS to allow the commit to proceed at all.

Unfortunately, CVS has a somewhat confusing behavior regarding sticky tags when adding new files to the repository. If a given CVS checkout has a sticky tag set, and you use cvs add to add a new file, CVS remembers that sticky tag, and assumes you want to add the new file onto a branch of that name. Sadly, CVS's internal access hooks don't consider this explicitly adding a new tag, so the tag access control script that we use on cvs.drupal.org does not have a chance to validate the tag and make sure it's a valid branch at this point. However, for your changes to take effect, you must also run cvs commit to really add your files, and that's where we can catch the error.

During every CVS commit operation, the CVS repository knows if your commit has a sticky tag, and if so, what it is. At that point, we validate the sticky tag and make sure it's a valid branch based on our own conventions and rules. We know it's already a branch since CVS checked that for us already. But, at this point, we can make sure it's a valid Drupal contributions branch, too.

The moral of the story is, "Don't do the crazy thing to add your branch in the first place, use the right branch name, and you should be fine."