How to Review & Test a Patch

01/14/2015 - 14:06 -- Kelly Lucas - G...

Reviewing patches in Drupal’s issue queues is a great way to get started contributing to the community. Regardless of your experience with Drupal, you can help out and learn a lot in a short amount of time.

Find an issue
The Drupal Global Sprint 2015-New England on Saturday, Jan. 17 at Genuine isn’t just about Drupal core, but if you want to work on Drupal core, here’s what you should do.

Finding a patch to a contributed module is similar, just omit the “Issue tags” filter as most contrib projects don’t tag their issues in that way.

Visually scan the list and pick one with a title that strikes you. If you’re just getting started, I recommend sticking with issues marked as priority “Normal”. You may need to read through a couple issues until you find one that’s up your alley.

Scroll to the bottom of the issue to see if, in fact, there’s a patch that needs to be reviewed. The patch box should be green which means the testbot applied it cleanly to a recent snapshot of the code and it didn’t break any automated tests.

Define the problem
Ideally, the issue title and description are all you need to understand the goal of the latest patch. Frequently though, and especially on contributed modules, that’s not the case. You’ll need to carefully read through the comments to understand the issue. This can often be the most time consuming part of the process.

If you do find that the issue title and description do not really describe the underlying problem or the goals of the issue as reflected in the comments, consider updating them to conform with the issue summary standards. Just take care not to hijack the issue.

Recreate the problem
Before you even deal with the patch, you should recreate the underlying problem on a fresh install. Setting up a Drupal install on your local machine is outside the scope of this post but that’s definitely one way to recreate the problem and certainly necessary if you want to work on code and potentially amend or re-roll the patch yourself.

A simple, free way to test a fresh install of Drupal is Simplytest.me. You can spin up a Drupal instance for free, installed with whatever contributed modules you need and hammer away at it. Register an account to extend the lifespan of your Simplytest.me instances.

Keep track of the steps you used to recreate the problem. You’ll want to duplicate them when you test the patch. If you are unable to recreate the problem, ask the original poster for more information in the issue comments.

Apply the patch
Simplytest.me makes spinning up a patched sandbox super easy. There’s even a link next to uploaded patches on Drupal.org.

To apply a patch to your local install follow these basic steps:

  1. Download and copy the patch to the root of the project.
  2. In a terminal window, change directory to the project root.
  3. Issue the command “patch < the-filename.patch”.

Applying a patch can be an unfortunately frustrating process, especially, it seems, for Windows users. The most common problem is identifying the directory referenced in the patch file. For Drupal core, this should be the same directory that contains the .htaccess and robots.txt files. For contributed modules, it should be the project root which is usually the same directory that contains the main .module file.

There’s a lot more about applying patches and troubleshooting on Drupal.org.

Sometimes patches won’t apply because the underlying code has changed since the patch was created and/or last tested by the testbot. If that’s the case, ask the patch creator to “re-roll” the patch.

Test the patch
Test the patch by following the exact steps you used to recreate the problem. Did the patch fix the problem?

  1. No. If the patch did not seem to fix the problem, add a comment to the issue queue describing your exact steps. Set the issue status to “Needs Work”.
  2. Yes, but… A patch may seem to fix an issue but there are a couple of things to consider.
    • Does the patch address the real, underlying problem?
    • Does the patch adhere to Drupal coding standards?
    • Does the patch contain tests?

If you answered “no” to any, mark as “Needs work” and describe your reservations. If the patch needs tests, tag it with “needs tests.” If you don’t feel qualified to judge a, b or c, add a comment to the issue queue describing your positive results but hold off on marking as “Reviewed and tested by the community.” Note that some contributed module maintainers don’t care much about b or c.

If the patch fixes the issue, adheres to Drupal coding standards, and contains automated tests, set the issue status to “Reviewed and tested by the community.”

Tips

  • There’s even more information on Drupal.org about reviewing patches.
  • The Dreditor browser extension can help a lot with reviewing patches and giving useful feedback.
  • Be nice! The patch creator probably spent a lot of time working through the problem. Always thank them and be gracious for their work, even if your results aren’t positive.
  • Have a thick skin. By the same token, it can be hard to communicate tone in these issue queues and sometimes people are working fast and with passion. Don’t let perceived rudeness dissuade you from continuing to help out.
  • Still have questions? Drupal Global Sprint 2015-New England will have mentors and OwnSourcing’s experts available to assist at Genuine.

    Please RSVP to reserve your space today. The Drupal Global Sprint 2015-New England will take place on Saturday, Jan. 17 from 10 a.m. to 5 p.m. at Genuine’s Boston office (500 Harrison Ave. 5R Boston, MA).