CVS Introduction

The Drupal development community uses the Concurrent Versions System (CVS) to manage all the revisions of every file that makes up the Drupal system. If you are unfamiliar with CVS, check out this brief tutorial before reading on. There are also many handy CVS cheat sheets, containing lists of commonly used commands for easy reference. Although it assumes some knowledge of CVS, everyone is encouraged to read the two page hand-out about maintaining releases that describes the essentials and best practices in condensed form. Additional links can be found at the Other CVS resources page.

The following general information describes how the Drupal project makes use of CVS to manage code.

Repository

Drupal has two repositories which can be checked out (downloaded to your local computer):

• drupal [description] [browse]
  The core Drupal code, i.e. what is downloaded as 'Drupal'.
• contributions [description] [browse]
  Modules, themes, translations, etc. supplied by contributors, i.e. all Drupal material that is not in the core.

Committing to the drupal repository

Only a few Drupal developers are able to make changes directly to the Drupal source code in the repository. All other users who want to include changes they've made while working on their local copy of Drupal must create a file showing the differences between their local version and the version at drupal.org. This file is known as a patch, and is sent to the rest of the development community by creating an issue in the Drupal core issue queue and attaching the patch file.

Committing to the contributions repository

Modules, themes or translations can be committed to the contributions repository at any time by users who have a CVS account on drupal.org. Each addition to the contributions repository is represented by a project home page on drupal.org, where its maintainer can describe the project and classify it into various categories, and where users can download releases and submit issues (bugs, feature requests, etc).

If you do not have a CVS account at drupal.org, but want to contribute your changes to a given project, you can still create patches and attach them to issues in that project's issue queue.

Branches and Tags

One of the most important and powerful features of CVS is the ability to create tags and branches.

• A branch is a way to isolate a set of changes to a group of files in the repository. You can make changes to files on a certain branch, and those modifications won't affect the same files on other branches. Drupal uses a different branch for each major version of Drupal core.
• A tag is a name given to an exact set of revisions of a group of files. Every time there is an official release of either Drupal core or a specific contribution, that release has a unique version number that identifies it. Before this version is released, a CVS tag is created in the appropriate repository to mark the exact revision of every file that went into that release.

It might be helpful to use an analogy to think about branches and tags. Imagine a living tree as it grows. At some point early in the life of the tree, it has a trunk and maybe a few small twig-like branches. As it ages, the younger, small branches grow thicker and longer, and new branches split off higher up on the trunk. Sometimes, new branches even split off from older branches. Say you wanted to keep track of how the tree was growing, and you decided to tie little paper tags with some word written on them whenever a branch first split off, and periodically at the ends of branches, so you could see how far the branches grew over time. To help you make sense of it, you use red paper for the tags at the start of the branches (and the word on those was a silly name you used to uniquely identify that particular branch), while the tags on the end of the branches at different points use purple paper.

With this growing tree in mind, the branches on the tree would correspond to ... that's right... branches in CVS. The only difference is that in CVS, you can decide when and where new branches split off. The red paper tags at the start of each branch are known in CVS officially as branch tags, or more commonly, just branches. In CVS (just like on your tree) knowing the little word written on the red tag (the name of the branch tag) allows you to identify that particular branch. The purple-colored tags at the ends of branches are known in CVS as tags. Every tag (branch or regular) has to have a unique name.

To continue the analogy (and translate it into software) each branch on the tree corresponds to a different major version of Drupal core. As bugs are fixed in a given release, the branch where the changes are committed would be growing longer (more revisions on that branch). Whenever a release is made, we take the most recent changes of the files (the revisions on the end of the branch) and add a tag to identify it (a marker with a word on it, in this case, based on the version number of the release) and tie it around the end of the branch.

In the contributions repository, it is now possible for project maintainers to create multiple branches that are all compatible with the same version of Drupal core. This is an example of a new, younger branch splitting off of an older, more mature branch, instead of branches always coming off of the trunk of your tree. It's all still associated with the same basic branch (at least in terms of where it split from the trunk -- a given version of Drupal core) but there are now separate branches where you make independent changes (new features) that don't disturb the natural growth of the original branch (stable code for bug fixes and security patches). As always, you can tie your paper tags to the ends of these branches and label how far they have grown whenever you want (to make a new release).

For more information, you can read about how Drupal uses branches and tags. For technical details, you can read the section about tags and the section about branches in the CVS manual.

HEAD

HEAD is the name that CVS uses to refer to the primary development branch in a repository. If you do not specify a revision for CVS commands like checkout or update, CVS will default to operating on the revisions in the HEAD of your repository. To continue the above analogy, the HEAD is the trunk of your tree.