When working on an issue during a Drupal sprint, (such as the upcoming 2015 Drupal Global Sprint weekend), you may find yourself needing to contribute code changes. Code changes are submitted to an issue using files known as patches. A patch is basically a file that lists the changes made to sets of files. To correctly create and submit patches, there are a few steps you should follow.
Step One: Prepare your environment.
Before you can create a patch, you need to make sure you have your local development environment setup. Take a look at the post “Useful Tools for Contributing to a Drupal Sprint” to get started. At the very minimum, you will need to have the following setup.
- GIT version control. (Optionally a GUI such as SourceTree)
- Your favorite IDE.
- A local running instance of Drupal.
- A drupal.org account
Step Two: Make your changes.
Before you can start making code changes, you need to first clone the GIT repository of the project. No matter what you are working on; Drupal 7 core, Drupal 8 core or a module, steps for how to clone the repository for a project can be found on the “version control” tab of the projects page on drupal.org.
After cloning the repository, you will want to create a local branch to use to make your changes. Make sure your branch is based off of the branch that the issue was reported on.
$git clone hit://[repository-uri].git my-project
$git checkout 7.x-1.x
$git checkout -b 7.x-1.x-my-changes
You are now ready to use your favorite IDE to make changes to the code. Be sure to test your changes on a local instance of Drupal.
Step Three: Generate your patch.
After you have finished making your code changes and you’ve tested that they work, you will want to generate the actual patch file. Depending on how you interact with GIT, there are many ways to generate a patch. I am going to demostraight how to create a patch from the command line, using the “git diff” command. Windows users can download unxutils to have access to this command.
After you have navigated to the directory of the GIT repository, running your local branch, you type the following command:
$git diff [original-branch] > [patchname].patch
With this command, we are telling git to compare the [original-branch] to your current branch and output any changes to the file [patchname].patch.
$git diff 7.x-1.x > my-changes.patch
Step Four: Submit your patch.
You are now about ready to submit your patch back to the issue on drupal.org. Before you do, you will want to make sure to rename your patch to follow the Drupal standards. The name of your patch should follow this format:
- Issue number, is the node id for the issue on drupal.org, you will find this at the end of the url for the issue on drupal.org.
- Description, is a brief description of what the patch changes.
- Delta, is a number. Usually it is the comment number you will use when submitting the patch.
You will now want to upload your patch to the issue on drupal.org. Be sure to comment about what your patch does and any notable changes you made.
After adding your patch, update the issue status to “Needs Review”. This will prompt other community members and maintainers to then test and review your patch to make sure it works.
Step Five: Maintain your patch.
After you have submitted your patch you are not done! A good contributor maintains their patches. Keep an eye on any feedback from other users about improvements and fixes that can be made to your patch. Then use that feedback to update your patch and make it better.
Following these steps will allow you to successfully create and submit patches that will hopefully be merged back into the Drupal project. If you need more help with patches there will be experts at the New England Drupal Global Sprint who will be happy to help you, so be sure to RSVP.