Last updated 7 January 2015.
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:
- Setting up development tools
- 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. 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.
Automated tools Installation
There is a scripted installation of most of the core tools you will require, this tries to be consistent across operating systems and has a small size to be nice to wifi resources.
The components this scripted process installs are:
The Drupal community uses irc actively. HexChat is highly recommended on Linux and Windows. On OS X we recommend LimeChat. The irc handbook page contains an explanation of the various Drupal IRC channels.
Mac and Linux come with a terminal. For Windows, Acquia Dev Desktop (ADD) comes with an integrated shell. Alternatively, Windows users can often just use the Drush Command Prompt or Git Bash that come with the Windows versions of Drush and Git (installed below). Otherwise, you will need to look at something like cygwin (Setting up Cygwin).
Local Web Server
There are many approaches to setting up a local web server. When starting out you may want to use a simple one click installer like Acquia Dev Desktop. You will find out about all the other options along the way.
Drush is a command line tool for Drupal.
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/drupalst3
Some extra tools you may want to install
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.
Integrated Development Environment
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 git pull
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.
There are many options for specific tools that can be found via google, wikipedia, and a more extensive list of choices on d.o. If you want to make a comparison listing the pros and cons with regards to a particular tool type, 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 from this page, but do not list all the options here. This is just a simple set of suggestions to get people started.