CVS reference guide for module maintainers

This document contains a series of CVS command examples that project maintainers can use to maintain their projects. Note that this document covers modules, but themes, theme engines, and translations are essentially the same. If you have problems or questions, please review the CVS FAQ to see if your question is answered there.

NOTE: if you are new to CVS and how Drupal.org uses it, you should follow more detailed instructions for Starting a new project and to Manage a project. This document provides very little context and assumes you know what you are doing.

There is a video about creating a new release that shows some of the steps on this page, specifically it applies a patch, commits the change, tags the release and then makes a new release node.

• Before you start
• Basics
• Logging in to CVS
• Adding a new module to CVS
• Saving changes to your module
• Obtaining latest changes
• Removing files from CVS
• Branching and tagging
• Before branching or tagging
• Branching for a specific Drupal core version
• Creating an official release
• Branching for new development versions of your module
• Creating a development snapshot release of your module
• Deleting a tag
• Saving changes to multiple branches

Before you start

Before you get started, you really should understand some basic concepts about Revision Control Systems, of which CVS is one. Please read the CVS Introduction and make sure you have a basic understanding before proceeding, particularly pay attention to the concepts of branches and tags.

Take some time to figure out the directory structure for your module. Renaming files in CVS is hard, and moving around directories is really hard (without the help of the extremely busy CVS admins.) If you have your directories structured and files named how you want them before your first CVS commit, you will save yourself (and those busy admins) a ton of grief.

When your module is ready for release, you'll need to apply for a CVS account. Also, note that you will need to create your project page on drupal.org before you start working with CVS. Check the step-by-step guide to creating new projects for more information.

Basics

Logging in to CVS

if you have not already done so, make the contributions repository your CVSROOT. At the command line:

cvs_username will correspond to the username you requested when you applied for a Drupal CVS account.

Next, log into CVS:

This will prompt you for your CVS password. Note that this is not necessarily the same as your drupal.org password!

Adding a new module to CVS

First, check out the modules directory from the HEAD version of the contributions repository:

The -l parameter (for "local") tells CVS to only check out the given directory, not all of the directories underneath it.

Next, copy your module files into the contributions/modules directory.

Finally, add your files to CVS.

NOTE: The cvs add command tells CVS that you want to add files to the repository, and it does not add directories recursively. If you have subdirectories then you will need to add each directory as above e.g cvs add example/subdir/*. The cvs commit command is used to commit your changes (in this case, the files you told CVS you wanted to add) to the repository, and the -m parameter is the "commit message", which tells people what changes you made to the repository and why. There is documentation on the commit messages handbook page on how to format CVS commit messages.

Saving changes to your module

Bugs and features are tracked in your project's issue queue. It is customary in the commit message to reference the node ID of the issue where the bug/feature request was raised, and mention any contributors who helped with the code. After making the changes in your local repository, you need to commit them to the CVS repository:

Obtaining latest changes

Both before you begin editing and before you save your changes, it's a good idea to grab the latest changes from CVS with the update command:

The cvs update command updates your local copy to the current state of the repository, and you can run it from the top level of your local copy, or any sub-directory to update only that sub-directory. The -d option ensures that you get new sub-directories that might have appeared, and the -P option "prunes" (removes) empty directories.

Removing files from CVS

While you cannot remove existing releases or actually remove files from CVS, it is possible to remove files from a branch. Sometimes a newer version of a module doesn't require a certain file anymore. If this file is foo.bar.inc, you need the following command to remove it:

Like cvs add, cvs remove tells CVS you want to remove the file, and it isn't actually removed until the cvs commit.

Branching and tagging

CVS allows you to keep different versions of your code active on different branches, and to tag different versions of your code. Drupal modules use CVS branches and tags in very specific ways, which are described fully on other pages:

• Read the CVS Introduction if you do not understand what CVS branches and tags are.
• Read the Release tags and version numbers page to learn how Drupal modules should tie CVS branch and tag IDs to released versions.

The sections below cover the CVS commands used for branching and tagging, and assume you have already figured out why you are branching and tagging, and what branch/tag ID you want to use.

Before branching or tagging

If you have just made the initial commit to a new module, you should have created a project on drupal.org before you started. If you didn't, do that now, before before proceeding with creating a branch or tag.

Before you enter the command to create a tag or branch, verify that the directory you're about to tag has the correct version of your code in it, that the code has been committed, and if you are tagging, that you are on the correct branch. In order to create a new branch, first change to the HEAD branch, and create your new branch as a copy of the HEAD branch, as shown in the examples below.

Branching for a specific Drupal core version

Branching indicates the code's compatibility with Drupal core. For more information on when to branch and why, read the overview of contributions branches and tags documentation.

For example, if you want to create a branch called "DRUPAL-6--1", you would use the following commands (after making sure you have the correct starting code committed and checked out):

The cvs tag -b command creates a branch, and is followed by the name of the branch you want to create.

Once you have created the branch, assuming you now want to work with that branch (modify code and check code in), you need to switch your local repository to using that branch. To do that:

Only run that from within your module's directory (example, here), or it will start downloading files for everything with that branch.

The -r option to cvs update tells CVS to update your repository to that particular branch, and to keep using that branch until you tell CVS to update to a different branch.

You can check which branch you are currently using by issuing a status command:

Look on each file for "Sticky Tag:" to be, in this example, DRUPAL-6--1 (followed by a CVS internal branch number) rather than "Sticky Tag: (none)" for HEAD.

Status will also tell you if you have changed anything that has not yet been committed to the repository.

You can go back to using the HEAD branch by issuing this command:

The -A flag tells CVS to reset to using no particular branch (i.e. HEAD), and to update the code to whatever is checked in on the HEAD branch.

Also, you may find it helpful to keep one local directory pointing to the HEAD branch, and other local directories pointing to each of your other branches. That way, you can have copies of each branch available at all times. To create a new local directory on a particular branch, use the CVS checkout (co) command:

The -d flag tells CVS to create a new directory with the given name; the -r command tells CVS which branch to check out.

Creating an official release

Once your module is stable, it's time to create an official release for it. Just as Drupal comes out with 5.0, 5.1, and such, you can (and should!) do this with your module. You do that by tagging your code.

Assuming you are already using the correct branch (see above), and that all of your changes have been committed, you can tag your code with DRUPAL-6--1-0 (the correct tag for the 6.x-1.0 release) with the following commands:

The cvs tag command tags all of the files in your project as belonging to a particular release. Note that you can tag a release as a "beta" by adding a suffix to the tag. For example:

After tagging the module for your release, you also need to create a release node for it, so that it shows up in the list of downloads on your project page on drupal.org.

Note that normally, releases should only be made after major bug fixes or security patches; not for minor bugs like whitespace fixes, small text fixes, and so on.

NOTE: If you find a security bug, please report the vulnerability to the Security team and do not commit fixes for the security vulnerability until told to do so by the security team. This gives the security team time to send an announcement out via the security newsletter and to make sure that the proposed fix for the bug actually fixes the security vulnerability.

Branching for new development versions of your module

Once a stable release of a module is created, you may want to continue to add features, leaving the original release of your module intact.

To create a branch for a new major version of your module (for example, version 2.0 of the Drupal 6.0 compatible version of your module), use the following commands:

Eventually, when version 2.0 is ready to be released you would tag the 2.0 version using the following commands:

You may want to edit your project node and click the 'releases' subtab and bump the major release also.

Creating a development snapshot release of your module

In order to allow people to test your module while it is in development, you may wish to make a development snapshot. This will create a "dev" snapshot which will always point to the newest version of the module in a particular branch.

To do so, make sure that the module is branched for the appropriate Drupal core version, and then create a release node pointing to that branch, rather than a specific release tag.

Note: Developer snapshots are only generated 2 times per day.

Deleting a tag

Note that it's a very bad idea to delete a branch once you have started committing changes to it.

Release nodes on drupal.org are typically never deleted. For more info about this please read the handbook page on Fixing releases. If you believe that it really is necessary to delete a release node, please submit an issue to the drupal.org webmasters queue, and one of the site maintainers will be able to delete the release node from drupal.org, but only if there is a very good reason for it.

In the event that there is a drupal.org release node pointing to the tag or branch you're trying to delete, CVS will display an error when you attempt to run these commands. You will need to first get the release deleted by filing an issue as indicated above, then delete the tag or branch; then create the tag or branch, and then re-create the release.

To delete a tag that was created in error, use the command:

If you need to delete a branch that was created in error, use the command:

Saving changes to multiple branches

When you commit bug fixes, if they span more than one version, they need to be committed to each affected branch.

So for example, if you have a 4.7.x-1.x and 4.7.x-2.x and 5.x-1.x version of your module, changes that affect both the 4.7.x and 5.x versions need to be committed to the DRUPAL-4-7, DRUPAL-4-7--2, and DRUPAL-5 branches.