Drupal Ladder - Re-roll patches to apply cleanly to the latest version of Drupal
In the previous stories, I wrote a patch and tested it. This post I’ll re-roll the patch follow this Lesson in Drupal Ladder.
In the time it takes to get a patch written, tested, reviewed, etc. Drupal continues evolving. As Drupal evolves, the patches must be kept up to date. For example, imagine a patch that was originally created to make some edits to line 5 in file X. Two releases later the patch should actually edit line 10, not line 5. Now the patch has to be updated, or “re-rolled”. Sometimes re-rolling a patch is complex, but usually it’s pretty simple. Git provides some handy tools that will let you apply the patch to the version of Drupal it was written for, merge the changes into a newer version, and then re-create the patch.
Before getting started, it helps to have a basic understanding of what we’re about to do with Git. You can read a brief overview of what’s going on in Git during the patch re-rolling process in the Re-roll patches to apply cleanly to the latest version of Drupal.
Here are steps…
1. Find patches that need to be reviewed.
I go to Drupal issue queue and find patches that need to be reviewed by filtering the list of issues tagged as Needs reroll.
2. Select the issue to work on.
In this post I select Fatal error when viewing node with content moderation enabled if a module which implements hook_node_grants() is enabled to work on. This issue needs patch re-rolling for Drupal 8.3.x. The patch is on comment #28.
3. Pull Drupal 8.3.x git
As I have to work on 8.3.x , so I pull the 8.3.x branch from git. Then, enter the Drupal root directory.
$ git clone --branch 8.3.x https://git.drupal.org/project/drupal.git
$ cd drupal4. Download the patch and try to apply it.
I download the patch and save it to Drupal root directory. Then, try to apply it with the command below.
$ git apply --check content_moderation_fatal_error_node_grants-2821716-28.patchThis will produce these error as the patch fail to apply:
>> error: patch failed: core/modules/content_moderation/src/Plugin/Validation/Constraint/ModerationStateConstraintValidator.php:126
>> error: core/modules/content_moderation/src/Plugin/Validation/Constraint/ModerationStateConstraintValidator.php: patch does not apply
>> error: patch failed: core/modules/content_moderation/src/Tests/NodeAccessTest.php:23
>> error: core/modules/content_moderation/src/Tests/NodeAccessTest.php: patch does not apply5. Create a local working branch to apply the patch.
Next I go to the issue and note the date of the comment that I downloaded the patch from and run git log to search for commit.
$ git log -1 --before="2 Dec 2016"
After that, create a new local working branch based on that commit where our patch applies cleanly. In the following example, node_grant will become the name of the new branch. You can choose a different name. 79569a7 is the commit hash.
$ git checkout -b node_grant 79569a76. Apply the patch to working branch.
I try to apply the patch to see if it works.
$ git apply --index content_moderation_fatal_error_node_grants-2821716–28.patchSince I see no output, the patch apply cleanly. If you get similar “patch does not apply” errors, delete your current branch and repeat the previous step with an earlier commit hash.
7. Commit the patch’s changes.
I commit the patch to my local working branch node_grant .
$ git commit -m "Applying patch from issue 2821716 comment 11806571"
8. Attempt to pull in all of the changes
Now, I will rebase to pull in all of the changes that have happened since the commit I branched from.
$ git rebase 8.3.x
Go through each of the files listed as having conflicts. Everything above the ======= is from the “clean” upstream version. Everything below the ======= is found in the patch you are rerolling. In general, you want to keep what’s in the clean upstream version, and then modify it to follow the changed behavior from the patch. This ensures that any other changes that have been made to the upstream version not affecting your patch do not accidentally get undone.
In my case, NodeAccessTest.php and ModerationStateConstraintValidator.php have conflicts.
I edit the files until it look correct, making sure to remove the special conflict marker lines.
9. Continue rebase process.
In order to continue rebase process, I need to stage my changes and run rebase continue command.
$ git add core/modules/content_moderation/src/Tests/NodeAccessTest.php core/modules/content_moderation/src/Plugin/Validation/Constraint/ModerationStateConstraintValidator.php$ git rebase --continue
Then git will output like this:
>>> Applying: Applying patch from issue 2821716 comment 11806571That means the rebase is successful.
10. Create and test your patch.
Finally, I create my patch by diffing local working branch node_grant against the upstream branch.
git diff 8.3.x node_grant > content_moderation_fatal_error_node_grants-2821716-32.patchThen, I check my patch by applying it to the main 8.3.x branch.
$ git checkout 8.3.x$ git apply --check content_moderation_fatal_error_node_grants-2821716-32.patch
If there is no output, the patch applies cleanly. Congratulations!
11. Upload it to the issue.
- Mark it back to “needs review!”
- Indicate whether it was an auto merge, if there were conflicts or if the file sizes were very different. If there were conflicts, describe what you did to resolve them. This will make it easier for the person reviewing the patch to know how carefully they need to review.
- Remove the “Needs reroll” tag.
Conclusion
From this lesson, I have learned how to use git rebase, how to search for a patch that needs reroll and helps Drupal communities reroll the patch. One more thing I experience is Drupal has a great automated patch testing.
P.S. While I was writing this post, someone had post a re-rolled patch before me ;)
