Last updated January 21, 2014.
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:
- Retrieving a copy of Drupal from version control
- Installing and configuring Drupal
- Finding and applying patches
- Testing patches for versions other than the current default
- 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.
Working on Drupal will be more efficient and pleasant with the right tools. These let you know what tools you will need. Some are optional but helpful depending on your focus. For some tasks, special tools might be handy and those are typically listed under in a specific Contributor Task Document. There are many options for specific tools that can be found via google and wikipedia. To make a comparison of listing the pros and cons with regards to what particular tool, for example IDE, to use with Drupal, please check to see if there is already a community document doing that comparison, and if not, create one. Link to it, but do not list all the options here. This is just a simple set of suggestions to get people started.
On a Mac, terminal is in the Applications/Utilities folder. For Windows, cygwin is common; get a shell that you can copy and paste text in and out of (http://cygwin.com/faq/faq.using.html#faq.using.copy-and-paste).
There are many approaches to setting up a web server. The Drupal Ladder lesson has some recommendations: Dev Desktop, MAMP, WAMP, virtual machines like Drupal Pro and Drupal Quickstart.
People love to debate editors and love their favorites. If you do not have a favorite yet, Sublime Text is a good one to start with. A Drupal focused setup tutorial can be found at http://rl.cm/PGmwVO
The Drupal community uses irc actively. The irc handbook page contains an explanation of the various Drupal IRC channels. ChatZilla is a common bowser plugin. Pidgin, aka Adium on Macs, is a good one.
Dreditor is optional but highly recommended. It's a browser plugin for Firefox and Chrome, that makes working on Drupal more enjoyable, easier, and faster.
Drush is a command line tool for Drupal.
An IDE is optional. Best to skip installing one until you need it.
Getting set up
Retrieving a copy of Drupal from version control
Testing these features requires a functional copy of the development version of Drupal, which is available from Drupal's Version control tab. For more information on Git, please refer to the Git documentation.
Follow the one-time only instructions on the tab for Setting up repository for the first time. For extensive directions on using the Version control tab, see Using your Version control tab.
Installing and Configuring Drupal
The 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
Once an interesting patch has been found, the process to apply the patch in order to test it is as follows:
- Ensure your copy of Drupal is updated to the most recent version. This can be done at any time by executing the following command inside the Drupal root directory:
- Download a copy of the most recent version of the patch (often patches are revised further down the issue page) by issuing the command:
OR, if you're on a system with curl rather than wget:
curl -O http://drupal.org/files/issues/patch-name.patch
- Apply the patch by issuing the following:
git apply [patchname].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 other version of Drupal
Not all patches in the patch queue are for the default branch of Drupal; bug fixes and security updates to release versions of Drupal will also appear here. When you cloned the Drupal repository, you obtained a copy of the entire repository. The version assigned to a patch and the version of Drupal to which it is applied must match, so use the following command to checkout the appropriate branch. For example, to work on Drupal 6.x, check it out, then fetch to ensure it's current.
git checkout 6.x
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 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.
Running tests locally
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.
Before running tests with a patch, run tests locally with no patch. If they do not all pass locally, or you have trouble getting something set up, try a search to see if there are instructions for setting up drupal on your specific system, or a solution for the error you are getting. Issues tagged with d8 dev environment might have a solution. If no solution is found, open an issue on drupal.org and tag it d8 dev environment.