If you've been working with Drupal for a while, you'll notice that sometimes, a particular module, theme (and sometimes even Drupal core) doesn't quite work right - or - perhaps it just doesn't quite work the way you'd like it to for your particular project.

Fortunately, this is the world of open-source, and you are most likely not the first person to have this problem (or "feature request"). Your first line of attack should always be to search the issue queue on http://drupal.org and see if someone else has fixed this problem for you (or added the new feature). Quite often, you'll find that they have, and there will be a patch in the queue.

This patch can be in one of many various states, my favorite is when it's already gone through the approval process, been committed to the project, and is already included in a stable release. At this point all you need to do to get the fix/feature on your own Drupal site is to upgrade to the version where the patch was committed. This just means updating to the latest stable release. YAY!

Sometimes the fix/feature has been committed to the project, but not included in a stable release. In this case you will need to update to the development version of the module (that's the scary red version that ends in -dev) and do some thorough testing either on a local copy of your website, or a 'dev' environment - someplace safe, where it will be okay if your site explodes. (Never upgrade to a dev release on a production website without testing first!)

If the patch for the fix/feature hasn't yet been committed to the project, you're going to need to apply the patch yourself. (See my tech tip on applying patches.) And if the patch adequately adds your fix/feature, you will need to learn how to maintain a sustainable development workflow that includes care for this patch.

Here's what I do:

For every Drupal project, I create a file that lives at sites/all/PATCHES.txt. This file includes a list of all patches currently applied to the project - core and contrib both. It also includes what was patched, why it needed to be patched, and a link to the comment that contains the patch that was applied.

Here's a real-world example from one of my Drupal sites:


Contact module (mail.inc)
Site sends mail as site-mail, not sender.

Node module:
Properly check permissions on node/add page.

Field module:
Properly trims content without broken HTML.

Contrib Modules:

New formatter with no pesky download link.

Auto NodeTitle:
Don't escape in titles.

Better formats
Clean up for WYSIWYG.

Comment wrapper content pane.

Re-enable global redirections.

Service Links:
Adds a pinterest widget.

Fixed redirect loop with reset button.

Allow better formats to work.

There are two main reasons to manage a list like this. The first one is that it will assure you are searching the issue queue for solutions for problems rather than doing it on your own (this will save you time in the long run, learn to use Open-Source to your advantage!). The second reason is that this simple file will also save you time (and sanity) during core and module updates.

For example: If a new version of WYSIWYG module comes out, my site will alert me that I need to update. I can check this file to see if I am maintaining any patches against WYSIWYG, and if I am, the first thing I should do is visit the URL I have also pasted in this file. From here I can see the status of the patch:

  • The patch has been committed, and is included in the new version. In this case I can delete the three lines related to this patch from my PATCHES.txt file.
  • The patch has been committed, but it's not in the latest release (it's still in the dev version): In this case I need to test the dev version of the module and make sure it's safe to run on my website before I deploy it. (PATCHES.txt file remains unchanged)
  • The patch has not been committed yet: In this case I can read any comments that have been added to the queue since I was last here, and find out why not. Did someone else find a problem with the approach taken int he patch? Is there a new patch? If there is a new patch I will try that one instead, and update the link in the PATCHES.txt file to point to the new comment where the latest (working) patch was submitted.
  • No one has looked at this issue fora while: Sometimes this happens, if this is the case try to apply the previous patch, and I also usually add a polite comment to the bottom of the issue saying something like "Patch still works for me! 7.21 + WYSIWYG 7.x-rc4" or if it doesn't still work, you can say that instead.

By reading the list of possible statuses of the patch above, it should be clear why it's not a good idea to simply include the patch files in your version control system, and try to re-apply the same ones after updating your code. (Something I've heard other developers mention they do.)

  1. The patch might have been committed already
  2. There might be something wrong with the old patch
  3. The old patch might have become obsolete

If any of the three above situations crop up, you'll wish you had a link to the issue handy so that you can find out what happened.

Why not start there and save yourself the trouble? :)