How to checkout Drupal from CVS, test, make and submit patches

Posted by matason on Tuesday, 17 November, 2009 - 21:58

Concurrent Versions System or CVS for short has been and is currently the version control system of choice for both Drupal core and also for contributed Drupal modules. For discussion on the future of version control for the Drupal project see http://drupal.org/node/289117 - Why is Drupal still using CVS and how can I help change that?

If you're running some flavour of Linux or Mac then you should be able to run CVS on the command line, Windows users (and Linux/Mac users for that matter) may prefer to download and use one of the available graphical CVS client programs. There's a handy list of these on drupal.org - http://drupal.org/handbook/cvs/clients

The Drupal core and contributed code repositories are listed here - http://drupal.org/repos

Let's perform the following tasks using CVS from the command line:

Checkout the latest version of Drupal 6

cvs -z6 -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal checkout -r DRUPAL-6-14 -d drupal6 drupal

The CVS options
-z6 is a global CVS option, it means compress the data that's transferred between client and server, 6 is the level of compression, 0 to 9 are the available options, 0 disables compression with the higher numbers giving greater compression.

-d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal is the CVS root directory pathname of the repository, this over-rides your $CVSROOT environment variable if you have one set.

This part of the command is a bit like a connection string:
-d for directory.
pserver is the protocol by which we access the repository.
anonymous the username.
cvs.drupal.org the host.
/cvs/drupal the repository path.

checkout is the actual CVS command, you could have used co for short.

The command options
-r for the revision you want, I used DRUPAL-6-14 which is the "tag" for the 6.14 release.

-d for directory, this is the second occurrence of -d, this time it's a command option and you specify name of the directory you want the checkout to go into, in my example drupal6.

The command argument
drupal - finally you tell CVS what you want to checkout.

Here's another example, this time checking out the latest Drupal code known as "HEAD" into a directory called "drupalhead":

cvs -z6 -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal checkout -d drupal_head drupal

And to update your working copy:

cvs update -dP

-d will create any directories locally that have been added to the repository.
-P will remove or "Prune" and directories locally that have been removed from the repository.

Checkout the latest Drupal 6 version of SimpleTest

On each contributed module project page there is a "CVS instructions" tab which contains instructions on how to checkout the module - see http://drupal.org/project/simpletest/cvs-instructions for example.

Here's the command for checking out SimpleTest 6.x-2.9.

cvs -z6 -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal-contrib checkout -r DRUPAL-6--2-9 -d simpletest contributions/modules/simpletest/

Apply/test a patch

Patch is a Unix program which can be used to update text files based on a set of instructions in another file (the patch), see http://en.wikipedia.org/wiki/Patch_(Unix) for more information about Patch and for Windows users looking to run Patch see http://gnuwin32.sourceforge.net/packages/patch.htm.

Fortunately SimpleTest comes with a patch in it's root directory, "D6-core-simpletest.patch", the Drupal 6 version of SimpleTest is a backport of the Drupal 7 SimpleTest code and if you want to run SimpleTest on Drupal 6 you'll need to apply this core patch.

Copy the file "D6-core-simpletest.patch" from the simpletest directory into the Drupal root directory and then from the Drupal root directory run the following command:

patch -p0 < D6-core-simpletest.patch

-p tells patch to strip (ignore) the leading components of file names so for example if the file names in the patch file have the base directory included use -p1 otherwise use -p0.

< D6-core-simpletest.patch is what is known as unix input redirection, what you're doing here is starting the patch program using the contents of the file "D6-core-simpletest.patch" as input. You could have alternatively used:

patch -p0 -i D6-core-simpletest.patch

Create a patch

Diff is a file comparison utility that can be used to create patches. More information about Diff is available at http://en.wikipedia.org/wiki/Diff and for users on Windows looking to run Diff see http://gnuwin32.sourceforge.net/packages/diffutils.htm

Assuming you've made some changes to the code you previously checked out, you can now create a patch with the following command:

cvs diff -up > module-name-issue-number.patch

-u tells diff to output some context for each change, the default is 3 lines but you can supply a number like -u4 for four lines.

-p instructs diff to show the function in which each change occurs.

These options tend make your patches more readable.

It's customary to name your patch file to include the "module-name" and the "issue-number" to which your patch relates, the issue number being the node ID of the issue (the number that appears after node/ in the URL). If you are raising a new issue, create the issue first, note the issue number and then attach your patch to the first comment.

It does require a little effort but it's pretty easy to get set up with CVS, you'll soon get the hang of applying/testing/creating patches. There are plenty of issues in the queue, http://drupal.org/project/issues, that are suitable for all levels of experience and usually there are plenty of people willing to help you get started in #drupal on irc.freenode.net. Check out the Lullabot "Introduction to the Drupal.org issue queue" video - http://www.lullabot.com/node/386/play for starters!

Quick Reference

Why is Drupal still using CVS and how can I help change that? - http://drupal.org/node/289117
CVS - http://www.nongnu.org/cvs/
CVS Manual - http://ximbiot.com/cvs/manual/
Drupal Handbook pages on CVS - http://drupal.org/handbook/cvs
Drupal core and contrib code repositories - http://drupal.org/repos
Patch - http://en.wikipedia.org/wiki/Patch_(Unix)
Patch for Windows - http://gnuwin32.sourceforge.net/packages/patch.htm
Applying patches - http://drupal.org/patch/apply
Creating patches - http://drupal.org/patch/create
Diff - http://en.wikipedia.org/wiki/Diff
Diff on Windows - http://gnuwin32.sourceforge.net/packages/diffutils.htm
Applying for a Drupal CVS account - http://drupal.org/cvs-account
Drupal.org issue queue - http://drupal.org/project/issues
Introduction to the Drupal.org issue queue - http://www.lullabot.com/node/386/play