CVS quick-start guide for module and theme 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 you question is answered there.

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
• 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.

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 changes to CVS.

NOTE: CVS 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/*.

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.

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:

Branching and tagging

Before branching or tagging

If you have just made the initial commit to a new module, create a project on drupal.org referencing your module before proceeding with creating a branch or tag.

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 managing branches documentation.

The following branches your module for Drupal 6.x:

Later, when you have finished porting your module to Drupal 7.x, when you are ready to release it, you would issue this command:

This creates a DRUPAL-7--1 branch, which you would then hold the versions of your module that are compatible with Drupal 7.x.

If you are creating the branch for Drupal 5.x or earlier, leave out the --1:

See the Branching for new development versions of your module section for further details regarding this difference.

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.

The following creates the initial 1.0 release of your Drupal 6.x-compatible module (6.x-1.0):

Note: Regarding the cvs update command, you should update to the branch matching where you are working. The example above assumes you want to release from your DRUPAL-6--1 branch. Releases for Drupal 6 could be made from HEAD, DRUPAL-6--1 or any other 6 branch, e.g. DRUPAL-6--2. In Drupal 5 it was permissible for a development branch to be named DRUPAL-5, in which case the update command above would be adapted as cvs update -dP -r DRUPAL-5.

If you later fix additional bugs in this module, you may want to put out a 1.1 release (6.x-1.1):

If you want to have a beta before release:

After tagging the module, it is also required to create a release node for it, so that it shows up in the list of downloads 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 have fixed a security bug you should work with the Security team to send an announcement out via the security newsletter.

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.

For versions 5.x and earlier of Drupal, the contributions repository allowed shortened branch names with an 'invisible' major release number for version 1.0 of a given module. For example, DRUPAL-4-7 was treated as if it were DRUPAL-4-7--1. Subsequent branches required proper major version numbers, for example: DRUPAL-4-7--2. To eliminate confusion, modules for versions 6.x and later of Drupal must use the full DRUPAL-X--Y branch names.

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

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:

Note that it's a very bad idea to delete a branch once you have started committing changes to 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 delete the release, then delete the tag or branch; then create the tag or branch, and then re-create the release.

Note: Only one of the site maintainers may delete a release node from drupal.org. If you think you need to delete a release node, please submit an issue to the drupal.org webmasters queue.

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.