Drupal patches: how they work and why they matter

“An open-source CMS” is one of the key things people first hear about Drupal. This means access to the source code and the freedom to cooperate on making it better. But the true benefits and spirit of a wonderful and diverse open-source community become clear to you when you work as its part.

Developers and other contributors unite their efforts to help Drupal shine brighter, and every contribution matters in the end. It’s amazing to see how drupallers in different corners of the globe come together to suggest new features, implement improvements, write documentation, review, and test the code of Drupal projects. In most cases, this is volunteer work in which people are willing to invest their time and effort — and, most importantly, they do it with great enthusiasm. Who can doubt this community is wonderful?

When it comes to improving Drupal, the community maintains its best practices, one of which is creating Drupal patches for projects. Let’s review what Drupal patches are, how they work in the community, and what makes them important.

What is a Drupal patch?

A patch is a small file that can be applied to the original code — for example, to a Drupal module or theme — so the code is further used in an improved way. Just like the main meaning of the word “patch” (a piece of cloth that strengthens a torn or weak point), a patch strengthens a project’s weak point.

A patch contains the list of changes made to the existing code. In addition to the new changes, it shows details of the new files, file deletion history, etc. Applying the patch edits the file without making a complete update. When it comes to the format, a patch file has a .patch extension. It contains a piece of code that can be extracted from there using the Git Diff command of the open-source version control system — Git.

Patches are created by anyone who wants to contribute, uploaded to the project’s page on drupal.org, and tested by the community, as well as by the automated testing infrastructure. They are indicated as green when they have passed the tests so it’s clear they are safe to be applied. Patches are easily found by anyone using search for specific issues.

What are Drupal patches for?

Patching is a fundamental Drupal technique. Its main mission is making quick changes to Drupal projects between the releases. For example, it may be necessary to fix a bug, add a new feature, or improve performance. Imagine a developer who has come across an interesting module that does not quite do everything this developer wants, so there is an option to create a patch, and someone else will also benefit from applying it. Through patches, the large community of attentive Drupal developers introduces new ideas to help make projects better and catch errors in time, so everyone wins.

Drupal patching: the good practice

Let’s see how patching is different from hacking and why this matters. Changing, also known as “hacking,” the Drupal core is a no-no in the community. It is one of the golden rules and best practices that every new developer learns from the start of working with Drupal. It is actually not recommended to change even contributed modules.

If you make direct changes to modules for your own use while keeping them invisible to other developers, this is not a developer-friendly approach and also makes it difficult to use the project in the future. For example, replacing the module with an updated version someday will mean losing all changes that have been previously made to it.

Patching introduces a better way to make the necessary changes. The changes are listed in a separate file so every developer in the Drupal community can see, review, or apply them if needed. It’s transparent and community-oriented.

It is also important to note that no effort should be wasted when it comes to Drupal contributions, so it is necessary to avoid duplicates. This will also maintain order on drupal.org, which is a pretty large and complex website. That’s why, as part of preparing for a patch creation, a developer needs to review the project’s page on drupal.org. There already might be a development version that includes the needed changes or a patch for a similar issue in the issue queue.

Drupal patches VS fork/merge workflow

It is worth mentioning that, in addition to patching, there is another approach to contributing source code changes to Drupal projects. It is relatively new — it has been around since November 2020 and it’s about using issue forks and merge requests. This approach is similar to that contributors use on websites like GitHub.

To make changes to a project, a developer forks it. This means the project gets a different temporary repository created for the new idea to be implemented. The contributor commits the new changes to the fork and makes a merge request that receives further automated testing and community review. Finally, the project maintainer approves the changes and merges them into the main repository.

When to use the fork/merge workflows as compared to Drupal patching? It is recommended that the fork/merge workflow is applied when the changes are big and or when there are many participants involved in making them. For smaller issues, patches remain a perfect solution.

Quick guide on how to create a patch for Drupal

• Find the latest branch of the module on its version control page on drupal.org. Clone it with the Git clone command using the instructions on the page for setting up the repository. Basically, you just need to copy the provided command to your terminal.
• Make all the changes you want to the code that reflect your idea of what needs to be improved. Test the changes well. To pack the changes into your patch, use the Git command via the command line or the GUI:
  
  git diff > patch_demo.patch
  
• Create a new issue with a summary in the issue queue of the project (or use an existing issue in the issue queue). It’s not yet the moment to attach your patch file. First, you will need to rename the patch file based on the Drupal community’s conventions:
  
  git diff > [short description of the patch’s goal]-[issue number (the nid of the issue node in its URL)]-[comment number (not the one in the URL but a regular comment number)].patch.
  
• Update the drupal.org issue with the comment and the patch file.
• Set its status to “Needs Review.”
• You can test the patch by adding it to the queue — just click “Add test” below the file.

Creating an interdiff

When there is a need to update an existing patch in a drupal.org issue, it is a good practice to create an interdiff. It is a text file in the .patch format that describes what has changed. This saves the reviewers’ time because they immediately know the difference between the two versions of the patch.

interdiff old-file.patch new-file.patch > interdiff-[issue_id]-[old_comment_number]-[new_comment_number].txt

Feel and boost the power of community!

If every member of the community uses the best practices of introducing new changes to Drupal, our favorite CMS will grow stronger. With Drupal patches applied in the right ways, projects will get the most relevant features, bugs will be eliminated in time, and drupal.org will be a user-friendly place where everything is easy to find. But, most importantly, Drupal experience, fresh approaches, and most innovative ideas will be shared across the community. Let’s be part of this all!