A sustainable development workflow for patching Drupal

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:

Core:
===========

Contact module (mail.inc)
http://drupal.org/node/111702#comment-7000314
Site sends mail as site-mail, not sender.

Node module:
http://drupal.org/node/1844330#comment-6748258
Properly check permissions on node/add page.

Field module:
http://drupal.org/node/221257#comment-4216314
Properly trims content without broken HTML.

Contrib Modules:
===========

Audiofield:
http://drupal.org/node/1061660#comment-6422898
New formatter with no pesky download link.

Auto NodeTitle:
http://drupal.org/node/565922#comment-6724458
Don't escape in titles.

Better formats
http://drupal.org/node/1706130#comment-6715542
Clean up for WYSIWYG.

Ctools
http://drupal.org/node/1771088#comment-6427820
Comment wrapper content pane.

Redirect:
http://drupal.org/node/905914#comment-6651084
Re-enable global redirections.

Service Links:
http://drupal.org/node/1411366#comment-5744512
Adds a pinterest widget.

Views:
http://drupal.org/node/1807916#comment-6711528
Fixed redirect loop with reset button.

WYSIWYG API:
http://drupal.org/node/934976#comment-6546146
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? :)

© 2024 Jeneration Web Development