Novice contributing 3: Create a patch

Last updated March 4, 2013.

Creating the patch

The issue is fixed by creating a patch and attaching it to the issue. Consult the following link to look for the steps to Making a Drupal Patch with Git http://drupal.org/node/707484 Use the GIT commands in that link to create a clean checkout, apply your changes, then create a patch (we want only the commands to fix the patch and nothing else).

The following command is the one that actually creates the patch itself:

git diff > [description]-[issue-number]-[comment-number].patch

The issue-number is the node name of the issue (e.g. http://drupal.org/node/1266348 is issue-number 1266348). The comment-number is the number of the comment that the patch will be uploaded into, since there may be multiple iterations of a patch prior to the issue being fixed. Eg : description-1266348-5.patch where 1266248 is the issue number and 5 is the comment to which the patch is attached.

Testing the patch

Before you upload the patch, test it. The following commands will create the patch, reset and refresh the environment, and then re-apply the patch:

Doing this will verify that the patch applies properly.

Proofreading the patch

Always proofread your patch before you submit it. Check for typos, unintended changes, or missing sections.

This is core - it needs to be clean and mean. Be sure to check for these ten common mistakes:

1. Each level of indentation should be two spaces.
2. There should not be any trailing whitespace at the end of lines added by your patch.
3. All files should end with a newline. If your patch says this:
   
   -}
+}
\ No newline at end of file
   
   You need to put the cursor at the end of that file and press enter.
4. All comments should begin with a capital letter and end with a period.
5. There should a space between // and the text of a comment:
   // This is a properly formatted inline comment.
6. Use complete sentences and clear language.
7. There should only be one space after a period. (Or none, if it's at the end of the line!)
8. All comment lines should be under 80 characters. Most code lines should also be under 80 characters.
9. All functions, classes, and methods should have docblocks. (See the documentation standards.)
10. All docblocks should begin with a one-line summary that:
    • Is 80 characters or fewer
    • Begins with a third-person verb in the present tense.
    • Explains what the function does.

    Example of a good summary: Logs a system message.

Code style resources and references

• If the coder module is available, run it on the files you've changed.
• Review the coding standards.
• Review the documentation standards.
• When in doubt, look at other code or ASK.

Interdiff

If there is another patch posted in the issue already, make an interdiff. This helps others who are reviewing your work, which in turn makes it more likely your patch will get reviewed faster.

Uploading the patch

Once you have created and double-checked the patch, upload the patch file (and interdiff) to the issue and switch the status to “needs review”. This will make the testbot run all of the project's SimpleTests with your patch applied.

Note: I often forget the "needs review" and the testbot never fires (it just sits there). If that happens, just create another comment and change it to "needs review".

Patching for multiple Drupal versions

When you create a patch, it should always be for whatever branch of Drupal the issue is currently on. So for instance, if it is a Drupal 8.x issue, create a patch against the Drupal 8.x branch.

After the patch is accepted and committed to that branch, if appropriate, the issue will be marked with status "patch (to be ported)", and the version will be moved to the next lower branch (7.x in this example). At that point (and not before!), it would be appropriate to return to your issue and make a 7.x patch.

Making patches for lower-numbered branches before the higher-number branch patch is accepted and committed is not recommended, because most patches go through several iterations. Trying to maintain two or more versions of a patch during that process can result in wasted time and effort. Also, some patches may apply to the previous version without modifications, if not too much has changed in that area of the code -- in this case, the committer will usually just apply the patch to both versions and it doesn't need to be ported at all.

Above all, do not change the Drupal version on an issue to a lower numbered version, for example from 8.x to 7.x. The only reasons to change the version number would be that the issue has already been fixed in the higher-numbered version, or that it never existed in the higher-numbered version.