Last updated 30 May 2014.

On this page:

To get help completing this task, see the Getting help completing your task page.

Goal

Create a patch for a Drupal version that applies a bug fix or other improvement, based on a patch that has already been committed to a later version. The reason this is required is that the Drupal backport policy requires that all fixes be applied to the in-development version of Drupal first. So, for instance, if Drupal 8 is in progress, any bugs found in Drupal 6 or 7 need to be fixed first in Drupal 8, and then back-ported to Drupal 7, and then to Drupal 6 (if appropriate). Often these patches need a small amount of work to be applied to previous versions.

Skills needed

You need to be able to understand, apply, and generate patch files (see reference information below if you want to learn). You also need to understand enough about code to see if a patch has applied correctly.

Detailed steps

  1. Install Git on your computer, if it is not already installed. See the installing git page for more information.
  2. Download the Drupal Core code base from Git for the version you want to backport a patch to. For instructions on how to download Drupal from Git, see Drupal core version control instructions (you might need to change the version at the top to find the right commands).
  3. Choose an issue marked "patch (to be ported)" (here's a search link). You can filter by version, to find an issue that needs to be backported to the version you are working with.
  4. Find the patch that was committed to the higher version of Drupal. You can usually find this by clicking the "latest attachment" link near the top of the issue page, or by using your browser to search for "to be ported", to see when the status was changed to "to be ported", and then going back a few comments to find the patch. Download the patch to your development machine.
  5. Scroll to the bottom of the issue, and assign it to yourself. Add a comment saying you are working on the backport.
  6. Attempt to apply the later-version patch to your repository:
    • In many cases when porting patches from Drupal 8 to Drupal 7, the patch just needs to be adjusted for the change in directory structure between D7 and D8. So, you may be able to apply the patch by using patch -p2 < path/you/saved/patch/in.patch (normally you would use patch -p1 to apply the patch to the same version). If the files haven't changed much, Git will adjust line numbers if necessary.
    • If that doesn't work, you will probably need to manually change the code by reading the patch file itself and applying the changes manually with a text editor or IDE. This is more error-prone, but it's a great way to understand how patches work.
    • It's also possible that part of the patch will apply and part will fail. In that case, the patch utility should make one or more ".rej" files, and you will just need to apply those sections manually.
  7. Confirm that the patch worked.
    • Examine the code to make sure the changed code looks correct.
    • Run git diff to look at what you have changed. Verify that it looks substantially the same as the patch you were trying to port.
    • Test the functionality, if possible. To do this, you will need to set up a test server. If the patch includes a test, run it. Make sure the code does not break your test site.
  8. Create a patch from your repository. First run git status to make sure that only the files you intended to change were changed, and that you haven't created any files unintentionally. Then use git diff > patchfilename.patch to create the patch.
  9. Attach your patch to the issue, add a comment saying you've backported the patch, and change the status to "needs review." Keep an eye on the issue to make sure it passes automatic testing and community review.

Background and reference information

Next steps: moving beyond this task

  • Write an automated test for a Drupal core bug.
  • Create a patch for a novice issue.
  • Supply a backport for an issue in another project, such as contributed module that you use. The steps above apply, except that you'll need to use the Git repository for that project, rather than Drupal core, and search in that project's issue queue.

Notes for reviewers

In general, follow the instructions for contributing as a reviewer and how to review patches. Keep in mind how to give constructive feedback.

Specific to backporting patches:

  • Compare the diffstat with the 8.x patch to double-check for missing hunks.
  • Search the change notifications for changes between D7 and D8.
  • Backports of bugfixes should be uploaded with a test-only patch followed by a combined patch.
  • Keep an eye out for API, UI, and string changes.