CVS guide for theme maintainers

This page is a reference for the CVS commands you will need to maintain a theme project on drupal.org. There is also a step-by-step guide to creating a project available in this section of the handbook.

Prerequisites

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 theme. 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 theme 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. There are also guidelines for making theme screen shots for your release page on http://drupal.org/node/11637

Initial theme release

Once you have a CVS contributor account and are ready to release your theme, follow the steps in this section to add your theme to the CVS repository.

The first thing you need to do is to make a local space for your theme repository:

Next, you need to set the CVSROOT environment variable, so that CVS knows which repository you want to connect to, and log in:

You will be asked for your CVS account password.

The next step is to "check out" the CVS theme repository (i.e. create a local copy of the repository). Because you probably don't want a copy of all of the other themes people have created for Drupal, use the -l parameter for the CVS checkout command, which will check out the directory without copying in all the files:

The next step is to copy in all of the theme files you want to release, making a new CVS directory (you should have chosen a "short name" for your project when you created the project page -- that is the name of your CVS directory).

At this point, double-check to make sure that if you do ls -lR your-theme-short-name, you see exactly the set of files that you want to release in your theme, with nothing missing or additional.

Now, it's time to use the cvs add command to tell CVS you are ready to add files to the repository, and then the cvs commit command to commit the addition of files to the repository. The CVS add command is not recursive, so you need to run it on the top directory, each file of the directory, and all the sub-directory files (if you have subdirectories):

Note that each commit to the repository has a "commit message" with it, which tells other people why you are making that particular change. There is documentation on how to format commit messages, so you might want to read that now.

Updating your theme

Eventually, you will find that you want to make some changes to your theme. To do that, just edit the files in your local repository, and test to make sure everything is working. It is a good idea also to file an issue in your project's issue queue, explaining why you are making the changes (new feature, bug report, etc.). Once your changes are ready to go to the repository (and thus be visible to others using the repository), you can commit them by running the following command from your repository directory:

The #12345 is the issue number to reference, and it is customary to acknowlege the user names of everyone who contributed code to the change.

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.

Branching

If your initial theme was created for Drupal 5.x, and now you are ready to start on a version for Drupal 6.x, it is time to create a new branch. Another possible reason for creating a branch is if you are going to make some major changes, and you want to change the major version of the theme (e.g. to go from version 6.x-1.x to 6.x-2.x).

To do this, start from the contrib directory in your local CVS repository space, and make sure all of your changes have been committed to the existing branch of your repository, and that you are updated to the latest files in the repository (see section above). Create the new branch by running the CVS tag -b command:

There is a full discussion of version numbers and corresponding branch numbers to use on http://drupal.org/node/93999

The next thing you need to do is to tell Drupal to start using your new branch (i.e. that new checkouts should go to your new branch instead of the HEAD or other branch you were using previously. You do that with the cvs update command we saw in the previous section, with an additional -r parameter, which 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.

Now, you can make any changes you would like for your new branch, and when you commit the changes, they will apply to the new branch. One useful command is cvs delete, which tells CVS that the branch you were using no longer needs a particular file:

This works the same as CVS add: it does not take effect until you commit the changes with a cvs commit command.

If you ever want to switch back to an old branch, just use the CVS update command again:

And to switch to the HEAD branch (which CVS considers not to be a branch at all):

Checking status

Another useful CVS command is cvs status, which tells you which branch you are currently using, and whether you have made any changes that have not yet been committed to CVS.

Tagging and releases

In order to release a version on your theme project page, you will need to tag the files in CVS. After ensuring that you are on the correct branch and that everything has been committed (see previous section for status command), use the cvs tag command to mark each file as part of your upcoming release:

This tag, DRUPAL-6--1-0 is the proper tag for the 6.x-1.0 version of your module; for other tag possibilities, check the branching and tagging versions handbook page.

Once you have tagged the files, you are ready to create a release node for your project. This is done by visiting your project page on drupal.org, and clicking on "Add a release" (you will need to log into your account on drupal.org if you were not already logged in). Note that there is a short delay between notifying drupal.org that you want to create a release, and its appearance on your project page.