CVS quick-start 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 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.

CVS tag/branch structure

The tags always look like DRUPAL dash core version number dash dash contrib branch number dash contrib release number. If you need extras, like beta you can add another dash and anything after that. The branches are DRUPAL dash core version number dash dash contrib branch number -- however with Drupal 5, there is no DRUPAL-5--1 it's called DRUPAL-5. There is no other difference for Drupal 5, so a tag would look like DRUPAL-5--1-4, and 2.x branches are like DRUPAL-5--2. Plenty of 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 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.

You can also just run cvs tag -b DRUPAL-5 in the example dir itself. Do not try to update to the branch before you created it.

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):

Note: despite the example above do not create a new tag and a release for every single commit! Create a new release only when there are ample bug fixes.

If you want to have a beta before release:

If you want to create a Drupal 5 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 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.