Last updated 8 June 2017.

This page lists the guidelines to submit a patch to a project, be it Drupal core or a contributed project. Following these guidelines will give your patch a better chance at being reviewed and committed. Additionally, Drupal core and contributed projects use the bot to run tests and valid patch styles are an important part of the test process. You can find information about actually creating a patch in the Making a Drupal patch with Git section.

Search the issue queue first

If you've found a bug, and have a fix for it, then there's always a chance that someone else has found the same bug, posted a bug report, and maybe posted a patch for it. If you find an existing issue for your bug - you can save a great deal of time by either reviewing existing patches on the issue, or posting your own there rather than starting a new issue. This has several benefits: patches only get committed when they've been reviewed and verified to work (usually by someone other than the project maintainer) - so if you post to an existing issue, then the other people who've commented will be notified that there's an update, and you have a much higher chance of someone else looking at your patch. Reviewing existing patches is also a great way to build your reputation in the community and get your own patches reviewed quicker later on. Make sure you also search issues without limiting the version since the same bug can be in multiple versions but only reported for one and bugs should be fixed in the latest version first.

Get the most recent development version

Patches against both core and contributed modules should always be posted against the most recent development version. If you find a bug in Drupal 6, there's a good chance that the same bug can be found in Drupal 7 or Drupal 8 (HEAD). You can find information about actually getting the most recent development version (and creating a patch) in the Making a Drupal patch with Git section.

Wherever possible, bugs are fixed in the latest development version first, and then backported to stable branches. This ensures consistent code between versions, that bugs fixed in older branches don't reappear in new releases, and because development versions usually have more activity - so the work of refining patches and ensuring the best solution can be efficiently carried out in the queue for that branch. This is often the case for contributed modules, although you should research the issue queues for those modules first in case they use a different system.

If your bug doesn't exist in the latest development version, then there's a chance it's been fixed there, and the patch needs backporting to the version you found it in - so again, search the issue queue first. If you can't find an existing issue, post to the most recent version where the bug can be found. If you find a bug in more than one version, you should not file an issue for each version. Instead submit the issue against the latest development version and attach a patch for each version you have fixed to the issue.

Read the coding style and security guidelines

If your code deviates too much from the Coding standards, it will be rejected without further review. You may want to check your code with the Coder module to help you find style errors. Well commented/documented code will also be looked upon favorably. Make sure your code follows the security guidelines! Obviously code that introduces security issues will be rejected.

Make your changes

Now that you have the most recent development version and you have read the coding style and security guidelines, you can make your changes. Always post against the most recent development version.

Describe your changes

Describe the details of the change(s) your patch includes and try to be as specific as possible. Note that we prefer technical reasoning above marketing: give clear reasons why "this way" is good. Justify your changes with solid reasoning. It is important to note the version to which this patch applies. To help people test your patch (vs. reviewing the code itself) you should also provide some basic instructions about what problems to look for or specific steps to take to see the effect of the patch in a test site.

Name your patch

This is an important step as it makes managing patches easier for people who work with many patches at once (e.g. core committers). Adopting a standardized naming convention such as [project_name]-[short-description]-[issue-number]-[comment-number]-[drupal-version].patch is very helpful.

For example, a patch for Drupal 7 about the forum module's comment titles attached to comment #15 of issue #12345 should be named: forum-comment-titles-12345-15-D7.patch

For patches that should not be tested by the testbot (for example, patches that do not work with the current API version in the issue), add "do-not-test" before the .patch. For example "forum-comment-titles-12345-15-D7-do-not-test.patch".

Caution Please do not include number signs (#) in your patch naming scheme until the issue #284899: Drupal url problem with clean urls has been fixed.

Verify your patch

Reviewers are overloaded reviewing and testing patch submissions. Please make their lives easier by assuring the following:

  • Provide evidence that your code works! Test your code.
  • If your patch is just a proof of concept or work in progress, then don't set your issue to "needs review" status, instead set it to "active" or "needs work".
  • For Drupal core, patch against the latest dev branch (head). (e.g. 8.x) If the patch is accepted into that branch, it can then be ported back to specific versions.
  • For contributed projects, you should patch against the branch corresponding to the latest development version (e.g. if the latest tarball listed on the project is [projectname]-7.x-1.x-dev.tar.gz, the corresponding branch is 7.x-1.x). Look at the bottom of the page for a list of available branches ("heads") at[project name].git, then after you've cloned the repository, check out the branch you want to patch. When you upload the patch, you should again specify the latest development version in your upload (that would be 7.x-1.x-dev in our running example).

Submit your patch

Patches should be submitted via the issue tracker. Create a bug report or feature request, attach your patch using the file upload form. Set the issue's status to "needs review" or "Reviewed and Tested By the Community". Setting the status to one of these options is important as it adds the issue to the patch queue.

Test patch locally before submission

Before submitting any patch, test your patch locally by enabling testing module. It would make sure that there is no test case failure due to this patch and during Automated patch testing there is less chance of failure. Once you are done with this, you can check by applying this patch locally to fresh version.


jonathan1055’s picture

The naming convention module-description-issuenumber-commentnumber-{optional-Dx}.patch is good but I also have three improvements I would like to suggest:

  1. Add an underscore _ at the start of the file name. This means that the files are listed separately from the actual module's files, which makes it easier to identify patch files, eg when upgrading a module or copying the patch files without getting them mixed up with the other real files.
  2. Have the issue number second in front of the description. The benefits are (a) you always get the patches in chronological order when viewed by name. In the current standard they are sorted by text of the description which makes it harder to find the latest one, and (b) it makes it easier to see the comment number if the two numbers are separated by text.
  3. Is there a reason why it has to be - between the parts, can it not be a . ? This makes the parts more easy to read, given that you can now have _ and - within the module name and textual description but will not have a dot here.

So my proposed standard for patch files in issue queues is:

Hopefully there will be some discussion here, and even get these changes into the standards.


agentrickard’s picture

I much prefer issuenumber_description_version.patch. The rest can be derived if you have a node id, and numeric files float to the top of most file sorts.

An underscore is an improvement, else the patch gets lost in the module files.