Goal: 
Backport a committed patch to an earlier branch of a project. Explanation: Patches (and merge requests) for software changes are normally committed to the latest development branch of a project. In some cases, the project maintainers decide that the patch should be adapted so that it will still work with an earlier branch of the project. In this case, the patch will need to be "backported" to the earlier branch.
Skills required: 
Using Git
Background and reference information: 
Life cycle of an issue
Creating or updating an issue report
Cloning a Module's project Git repository
Applying a patch in a feature branch
Making a patch
Creating issue forks
Detailed steps: 
  1. Set up prerequisites: Log in, Git, and either Online testing site or Local development site from Common Prerequisites for Contributors.
  2. Find an issue whose status is "Patch (to be ported)" in a project that interests you. For example, use this link to search Drupal core for Patch (to be ported). Click the issue title to open the issue page.
  3. Search in your browser for the text "Patch (to be ported)", to locate the comment where the status was changed. Read this comment (and possibly the previous few comments) to:
    • Verify that the status is correct (that there is a patch that needs to be ported).
    • Find the patch that was committed. If the issue used a merge request instead of a patch, you'll need to download a patch file from the merge request. See the "Downloading a patch file" section of Creating issue forks and merge requests for more information.
    • Figure out what version the committed patch applied to.
    • Figure out what version it needs to be ported to.
  4. If necessary, create a new issue to work on the backport. A new issue is necessary if one or more of the following applies:
    • The original patch is for Drupal 8 or later and it needs to be ported back to Drupal 7
    • For projects other than Drupal core, the project has undergone major changes between the version the original patch is for and the version to be ported to
    • The maintainer requested a new issue

    The easiest way to create a new issue is to click the clone issue link in the sidebar (between the "Jump to comment" links and the Related issues section). You'll need to change the Version field to the version you are creating the patch for, and explain in the issue summary and title that this is an issue to backport a patch.

  5. If you created a new issue, add a comment to the original issue with a link to the new issue, change the original issue's status to "Fixed", and click Save to update the original issue. For the rest of this task, all issue updates will be in the new issue.
  6. Add a comment to the issue you are using for the backport, saying you are backporting the patch.
  7. Use Git to clone or update the repository for the project, and check out the version you are porting the patch to.
  8. Attempt to apply the original patch to your repository. One or more of the following may happen:
    • The patch may apply with no warnings or errors. Hooray!
    • The patch may apply with some "fuzz", meaning that line numbers changed substantially, or that context lines around the changes in the patch were slightly different. This is usually OK.
    • If you are porting a Drupal core patch from Drupal 8+ to Drupal 7, the patch will need to be adjusted for the change in directory structure between D7 and D8 (Drupal 8+ has many similar files to Drupal 7, but they're under the top-level core directory). Try applying 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.
    • Sometimes files move to other locations or are renamed. The patch utility should prompt you when it cannot find a file that needs to be patched, to ask you to enter a new file name and path, and then it will attempt to apply the patch to that file.
    • The patch may not apply at all. In that case, you will 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.
    • Part of the patch could apply and part could fail. In that case, the patch utility should make one or more ".rej" files, and you will need to use the manual method for only those sections of the patch file.
  9. Confirm that the code changes are correct:
    • 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 on a development site.
    • If the patch includes an automated test, run the test.
  10. Create a patch from your repository.
  11. 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.