Setting up a test environment to review patches

This guide is aimed at a developer or end user who would like to participate in the Drupal core patch review process, but is unsure of where to start. A similar process will work for contributed modules, but this page's focus is on core. There are five main sections to this guide:

1. Retrieving a copy of Drupal HEAD from CVS
2. Configuring Drupal HEAD
3. Finding and applying patches
4. Testing patches for versions other than Drupal HEAD
5. Creating a test environment from an existing installation of Drupal

This document assumes the reader has shell access to some sort of Linux/Unix/BSD/Cygwin platform.

Retrieving a copy of Drupal HEAD from CVS

Drupal HEAD is where work on the next version of Drupal always occurs, so it is against this version of Drupal that any new features will be developed. Testing these features requires a functional copy of the development version of Drupal, which is available from Drupal's CVS repository. For more information on CVS, please refer to the CVS section of the handbook.

1. Begin by creating a directory to contain the new version of Drupal. For example,
   cd /path/to/web/root/

2. The next step is to retrieve a copy of Drupal HEAD from the server. Execute the command:
   cvs -z9 -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal checkout -d drupal-cvs drupal

   This will download the Drupal HEAD files to a folder called drupal-cvs.

Configuring Drupal HEAD

Drupal HEAD's installation and configuration is generally done in exactly the same way as a standard version of Drupal (see the Installing Drupal section of the handbook for more information). After completing the steps in INSTALL.txt, test the installation to ensure it is working properly.

Finding and applying patches

Patches can be found in the Drupal Patch Queue. Choose from patches which match the Drupal installation (in this case, cvs; see below for instructions on testing patches on other versions of Drupal). An excellent guide to reviewing patches can be found at Tips for reviewing patches in the Contributor's Handbook.

Once an interesting patch has been found, the process to apply the patch in order to test it is as follows:

1. Ensure Drupal HEAD is updated to the most recent version. This can be done at any time by executing the following command inside the Drupal HEAD root directory:
   
   cvs update -dP
2. Download a copy of the most recent version of the patch (often patches are revised further down the issue page) by issuing the command:
   
   wget http://drupal.org/files/issues/patch-name.patch
3. Apply the patch by issuing the following:
   
   patch -p0 -u < patch-name.patch

Finally, test the patch out rigorously and submit feedback to the issue tracker, in order to help identify problems and improve the functionality of Drupal.

Testing patches for versions other than Drupal HEAD

Not all patches in the patch queue are for Drupal HEAD; bug fixes and security updates to release versions of Drupal will also appear here. To setup a test environment for patches other than those intended for Drupal HEAD (for example, Drupal 4.6.1), generally the same steps as above are followed with the following exception:

When retrieving a copy of Drupal from CVS, the same checkout command is used, however a branch must be specified in order to retrieve a version of Drupal other than HEAD. A list of available branches is available from the Using CVS with branches and tags page of the Contributor's Handbook.

For example, to checkout a test version of Drupal 4.6.1, use the command:

Remember that the version assigned to a patch and the version of Drupal to which it is applied must match.

Creating a test environment from an existing installation of Drupal

The best way to see how a patch will affect an already-live installation of Drupal is to apply it directly. However, since patches can sometimes yield unexpected results, the best course of action is always to apply them to a copy of the live installation rather than the installation itself.

Some additional tips

• Create a test site containing a variety of different roles, blocks, nodes and comments; testing with a clean installation makes very little sense for a lot of tests. devel_generate module can generate sample content, taxonomy and users.
• A good way to maintain a certain set of patches is to do so on a test site dedicated to testing only those patches. That way you can be sure that patches do not conflict, or that a previous test doesn't breaks the current one.

Here is what I do:

1. mkdir 28245 (the number is the issue/bug/node id
2. mysqlhotcopy the "clean" database in there with dbname 28245
3. edit settings.php to use myhost/28245 as url and 28245 as database.

This might seem like a lot of work, but it is well worth it.

Another Option

The simpletest module is another great way to test Drupal. It runs a series of automated tests and alerts you if there's an error. It is useful for testing how new patches affect the core, etc.