How to contribute a patch to Drupal.org

Drupal logo on blue background

When a contrib module needs patching, that patch should be submitted upstream to the maintainers of the module on drupal.org. This means that domain-specific business logic should not be patched into contrib modules. Instead, where necessary, submit a patch to the upstream module to expose an alter hook. Then put your domain-specific business logic in a custom module which implements that alter hook.

In order to open issues or contribute patches on Drupal.org, you will need to have a drupal.org login.

A. Precisely identify the problem.

Let’s say that you identify a shortcoming within a contrib module. First, make sure the module is up-to-date. If not, your first step should be to update to the latest stable version. If the problem still exists, check to see if it has been addressed in that module’s dev version (which corresponds to git master on Drupal.org).

If you have well established that the upstream developers have not merged a fix for your problem, you should check that project’s issue queue on Drupal.org. It is likely that someone else has encountered the same problem, and they may have posted a patch to resolve it. You should very carefully test any patches posted on drupal.org which have not been merged into upstream’s master. (It goes without saying that you should limit your searches to the appropriate level of Drupal compatibility — for FCC, for example, stick to version 7.x of whatever module it is you are searching.) If you apply a patch from a Drupal issue queue, you should make yourself a watcher of that issue, so you will know if a more comprehensive patch is later posted, or if the patch is accepted into git master.

B. Nobody else has reported this issue; what next?

The next step is to create an issue in the Drupal queue for the relevant project. I recommend you read ESR’s “How to ask questions” essay if you’ve never read it before. Gather all the relevant data and present your problem clearly. If you can pinpoint the problematic part of the code, so much the better!

C. Prepare a patch.

If you feel you can address the issue yourself, it’s time to prepare a patch for upload. You should already have opened an issue in step B above; these issues are Drupal nodes, and you should take note of the node ID of your issue.

  1. Clone the appropriate versioned branch of the module. You can find the repo URI and branch name by browsing to http://cgit.drupalcode.org/<project_name>. The git URI is at the bottom of that page, and the branches are listed at the top. Do not clone master! On drupal.org, master is not used. You want the highest numbered branch corresponding to the Drupal major version you are coding against.
  2. Make your changes to your newly-cloned codebase. Run phpcs --standard=Drupal on any code you have changed, and make sure everything is formatted correctly. Code against the version of PHP that the module says it supports (for example, if a module does not directly declare a PHP version in its .info file, or declares php = 5.3, do not use short array syntax). If you are adding a hook, make sure you document the hook in module_name.api.php (you may create this file if it doesn’t exist yet).
  3. Take another look at the issue you created above. Note the last comment number. You will use that in creating a filename for your patch.
  4. Create your patch: git diff > ~/<issue_nid>-<module_name>-<short_description>-<next_comment_num>.patch
  5. Attach this patch to the Drupal issue. Nobody will scream if the comment number doesn’t exactly line up, but you should do your best.
  6. If you think your patch is ready for the maintainers to merge it without further discussion, set the issue status to “Needs Review.” If the maintainers have issues with your patch, they may reset status to “Needs Work,” with suggestions as to how to improve your patch.
  7. Continue to watch the issue in the queue so you will know if/when it is merged to master. You may also want to let others on the team know about these issues so they can add themselves as watchers too.