Write a patch

Ready for review -- Last peer review: 29 Jun 2014
Description: 
Learn to submit suggested changes to Drupal as patch files
Overview: 

In this exercise you will create a patch to resolve the issue created in the previous exercise. Then you will post this patch along with before and after screen shots as a proposed solution to the issue.
Currently, this tutorial only has instructions for working with Git on the command line.

Resources
There is a short video, Writing a patch, that walks through this lesson.

Prerequisites: 
  • You'll be working with a sandbox version of Drupal in this exercise. It has been built with a known issue for you to patch. For this lesson, download and install Drupal 8 from the Drupal 8 Sandbox for Drupal Ladder
  • Install Git
  • An issue in the sandbox issue queue, as created in the Getting started in the issue queue lesson. You will need to know your issue number, which is the node ID for the issue on Drupal.org. You can easily find this by going to the issue page and then selecting the node ID from the page URL. E.g. if the issue page URL is http://drupal.org/node/1681300, the node ID, and therefore the issue ID is 1681300. Make note of this for reference in this lesson.
  • Basic Git knowledge is helpful but not required (Git Basics, Git Reference)
  • A way to capture screen shots. Popular options include: Skitch, Jing, or Awesome Screenshot
Steps: 

Tip: In the steps treat [things in square brackets] as blanks to fill in. Therefore, replace [issue-number] with your actual issue number such as 1234.

Create a branch for development

  1. Go to your Drupal 8 sandbox.
    cd path/to/drupal-8/sandbox
  2. Check what branch you're in and make sure you are in 8.x.
    git branch
  3. Create a branch where you will work on your patch.
    git branch [issue-number]-rewrite-description-for-url-alias
  4. Now check out the branch you just created.
    git checkout [issue-number]-rewrite-description-for-url-alias
  5. Confirm you're on the branch you just created.
    git branch

Make your edits.

  1. Open the path.module file (e.g. my-sandbox/core/modules/path/path.module) with your favorite text editor.
  2. Go to line 139 and replace this:
    Optionally specify an alternative URL by which this content can be accessed. For example, type "about" when writing an about page. Use a relative path and don't add a trailing slash or the URL alias won't work.
    with this:
    The alternative URL for this content. Use a relative path without a trailing slash. For example, type "about" for the about page.
  3. In your browser, go to Content > + Add content > Article (node/add/article), scroll down and click the URL path settings tab. Confirm your edit worked by seeing that the help text as changed, and confirm you didn't accidentally introduce an error.
  4. Take a screen shot. Using your screenshot program, call out out the changed text with an arrow or highlight. (You will upload this along with your patch.)
  5. See which files have changes pending.
    git status
  6. Review your changes in Git with a standard diff. (Note to exit the patch display, type the letter q on your command line to quit viewing.)
    git diff
    You can also review your changes word-by-word.
    git diff --word-diff
  7. If you made a mistake, you can undo all of your changes.
    git reset --hard
  8. Commit your changes on your local development branch. The "-am" flag in this command is adding (a) the modified file to the local git repository with the message (m) that you provide being added to the git log.
    git commit -am "Issue #[issue-number]. Updated description for URL alias on node form."
    (When you commit your changes, git may generate and display a commit ID. The commit ID is a 40 character code, e.g. bc584d4ff96d434706211e2bef45613dd32d3c16. You can use this ID to refer to and review your commit.)
  9. Review your commit.
    git log
    git show
    Or
    git show [commit ID]

Create and submit a patch

  1. Figure out which comment number your patch will be attached to. Go to the issue and scroll down through the comments. Note the comment number for the last comment. Your patch will be attached to the next comment, so you will use that next sequential number for your patch. E.g. if the issue has 3 existing comments, your patch will be attached to comment 4. You will use the number 4 as part of your patch name in the next step.
  2. Generate a patch file using the following naming convention. Note that the patch filename cannot contain any spaces, so use dashes or underscores to separate words and numbers. This is taking the output of the git diff, which shows the changes between your branch and 8.x, and creating a file with that text, which ends in .patch
    git diff 8.x > [description]-[issue-number]-[comment-number].patch
  3. Test your patch by applying it to a branch before uploading in a issue queue, you can use the 8.x brach for this :
    Checkout to the 8.x branch
    git checkout 8.x
    Apply the patch
    git apply -v [description]-[issue-number]-[comment-number].patch
    If the patch applies successfully, you can now upload your patch to the issue, but first, undo the changes done by the patch in the 8.x branch.
    git reset --hard
  4. Go to your issue on Drupal.org.
  5. Post a comment on the issue and upload your patch and screenshot.
  6. Change status settings of the issue to "Needs Review"

    Status settings of issues: https://www.drupal.org/node/156119
    Changing the status to ‘needs review’ will trigger the testbot, which will then automatically review the patch and will display the results. Patch Reviewers also use this status to find patches that need to be reviewed and evaluated. With sufficient positive feedback, the patch may be promoted to the status “Reviewed & Tested by the Community” [see next definition]. If a reviewer, either human or Bot, finds a problem with the patch, it will then be marked as “Needs Work”. Note that if a patch is not required in order to complete the idea described in the issue, then it is the idea itself that needs review. You can see what other status settings do on this page.
  7. * Note: Normally you would now wait for the testbot to test your patch. This is a sandbox issue queue, so the testbot WILL NOT test your patch here. When you do post in a regular issue queue, the testbot will check your patch to make sure it doesn't break anything. If your patch turns green, the patch applied cleanly and passed Drupal's tests. Now if your patch passes tests by other members of the community, it can be committed. If your patch turns red, tests failed. Click the link for View details to see what's going wrong, then re-write and re-submit your patch.

Bonus: Re-roll the patch
In the real patch to this issue, http://drupal.org/node/1326088#comment-5188202, the word 'type' was changed to 'enter' before it was finally committed. This means the patch can no longer be applied to the updated code base. The patch must thus be updated, or "re-rolled" to be compatible with the current version.

  1. Checkout your development branch.
    git checkout my-branch
  2. Make your edit, by changing the word 'type' to 'enter.'
  3. Commit.
    git commit -am "Issue #[issue-number]. [Description]."
  4. Create a new patch with the updates.
    git diff 8.x > [description]-[issue-number]-[comment-number].patch

Comments

KrisBulman's picture

There is no way of knowing if your patch applies cleanly using these instructions, a step should be added to revert to a change before your patch, then apply it to assure it applies cleanly.

Great lesson: only a couple of suggestions that might help total beginners like me:
Under 'Create and submit a patch' - After number 2: I would add a short sentence explaining that the patch is automatically saved in the drupal root folder

Under 'Bonus: Re-roll the patch":
This section is confusing to me, a total beginner. It is not very clear what a re-roll is for...a better introduction would be appreciated
Also, I guess you are suggesting to checkout the branch that was created at the beginning of the lesson but it is not clear; as I moved from the previous section to this bonus section in succession I am still on the new branch I created. Silly, I know, but I wonder if this bonus section is needed or more confusing.

Hi Guys

I think you need to update the steps in the section: Create and submit a patch. Between step #4 and #5 I believe it requires an extra step, which could be detailed along the lines of the following:

You then need to update the issue and set the status to 'Needs Review', to initiate an automated test of the patch.

The Testing Bot uses this status to trigger an automated review of the patch, and reports the results.

Ref. Status settings for an issue: https://drupal.org/node/156119

Note that the Test Bot is not necessarily triggered immediately and you may need to check back after a short while, to see the results of the automated patch review.

It helped me get started on Drupal patch contribution , Awesome tutorial! :)

Re-roll
It would help if the conditions under which re-roll of a patch happens.