Today we're moving on to step 5. Be sure to catch part one, part two and part three of these series. If you have any questions, I can be reached on drupal.org at trgreen17.

Step 5: Create a patch and an interdiff and upload them to the issue.

In simple terms a patch is a fix for existing code. At this point in your Drupal life you’ve probably applied patches to contrib modules in between official releases. That’s exactly what we’re doing here, fixing the code so a new version (commit) can be made. An interdiff is a simple but crucial concept. It is the difference between your patch and the one before it. It’s not used in the code, but it lets developers more easily see what you’re doing by showing only the lines that have changed, so they don’t have to read your entire patch. I’ve already learned to read the interdiff first, it gives me an idea of what the developer was going for when he or she created their patch.

Create a patch. After you complete your changes you will have one or more uncommitted files in your codebase. You will want to use the git add command to commit them so your patch will know to include their changes. It’s always a good idea to issue a git status command to see if the updated files are the ones you expected to see:

The results of that command tell us that two files (simpletest.module and WebTestBase.php) have been changed and committed to the project, but also that WebTestBase.php has been changed again and not yet added. So after running the command:

you will see the same image as above but with both of them in green and no red file to be added.

At this point we’re ready to create the patch. In order to do that, get a suggested patch name by clicking the “Patchname suggestion” button in the “Files” section near the bottom of the issue page. This assumes that you installed the Dreditor plugin for your browser, which adds that button. If you didn’t, you’ll need to decide on the patch name yourself. Your patch name should include, at the very least, the issue number and the number of the comment you’re uploading your patch and interdiff files to. This helps us keep patch names consistent and appropriate. Once you have a patch name, and making sure you’re in the root of your codebase, simply run the git diff command to create your patch, like so:

git diff origin/8.0.x > suggested_patchname10.patch

This will create the patch file in your root. This patch will contain all of the changes (including any previous patches) in your current codebase and the origin, which is Drupal core 8.0.x. Congratulations, you just made your first core patch! It still needs to be tested and approved, but you’re on your way.

So now it’s time to create the interdiff. I used “suggested_patchname10.patch” above for a reason. Let’s say that your previous patch was named “suggested_patchname6.patch.” Notice the numbers that were skipped? This is because Dreditor will change the suggested name to the number of the comment that you’re on. So if there were three non-patch comments since your last patch, the plugin is smart enough to suggest the most current comment number for the patch name. Tip: I always refresh the page before I get the suggested patch name in case someone has posted a non-patch comment in the meantime. I’m not sure if that’s necessary, the patch name button may query the database before it suggests a name, but it can’t hurt.

Okay, back to the interdiff. Again, the purpose of the interdiff is to show only the changes since the last patch, and this is apparent if you look at the command used to create it:

interdiff suggested_patchname6.patch suggested_patchname10.patch  > interdiff- 2299361-6-10.txt

If you look at the command you can see what’s happening, we’re creating a difference file between the previous patch (6) and the current patch (10) and writing that file in your root, that includes the issue number and the two comment numbers. It’s a good system and it makes complete sense. Okay, now for the fun part, post your patch and see if it passes the automated tests!

Now, refresh your issue page and go to the bottom, to the comment box. There are several things to do here:

• Make a short post about what you did and perhaps what your patch is responding to.
• Change the status of the project to “Needs review.” This tells the d.o. testing system to examine your patch for syntax and it puts it in the queue to be tested.
• And finally, using the Files section, upload both your patch and your interdiff.
• Save the comment and wait for the test results. Tick-tock, in my experience it takes anywhere from ten to twenty minutes, but I’m sure it depends on the current load.

Step 6: Await the automated testing results and recommendations from the community

Once the testing is complete you’ll receive an email letting you know the results. If your test passed, other “watchers” of the issue, and perhaps the issue author, will then comment and let you know if your patch is correct. Notice that there is a difference between just having a patch that passes the tests and having a patch that is correct for your given situation. If you read my issue, you’ll see that several of my first patches passed the tests, but weren’t exactly what we were after, insofar as properly documenting the testing module.

Here’s an example of a patch that passed the tests:

If your patch fails the test, the issue status will automatically be set to “Needs work” and you’ll see your patch with red text and several links.

You can see the links in the image above. You can click on the patch or the interdiff to read them in your browser, but the most useful one here is the “View” link. It will take you to a page with detailed explanations of why your patch failed. Then it’s up to you to:

• Fix the errors.
• Create a new patch with the suggested patch name.
• Create a new interdiff between the new patch and the one that failed.
• Upload them and set the status to “Needs review.”
• Await the test results

Tomorrow we'll be wrapping up this series so be sure to check back in. Until then, happy contributing!