Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.
Goal:
Create a patch (software fix) for a contributed module, theme, or distribution that already has a Drupal 8 release, to make it Drupal 9 compatible.
Skills required:
Detailed steps:
- Set up prerequisites: Log in, Git, and Local development site from Common Prerequisites for Contributors.
- Choose a project to work on that has a Drupal 8-compatible release, has no Drupal 9-compatible release, and that has at least some Drupal 9 compatibility errors that cannot be fixed automatically. This could be a project you maintain, or a project with a "Needs manual review" or "Some covered by rector" result on the Drupal 9 Deprecation Status tracker from Acquia. (See the Test a Drupal 9 compatibility patch task writeup for projects where automatic fixes are sufficient.)
- Find the project's issue list on drupal.org, and use a keyword search to see if there is already an issue about Drupal 9 compatibility. (Note that if you are on the Acquia project deprecation tracker, the project Name in the left column is the URL suffix on drupal.org -- for example, if the Name is database_sanitize, the project's home page is at drupal.org/project/database_sanitize.) You can also check the project's home page for Drupal 9 compatibility information -- some projects have a link to a Drupal 9 compatibility issue there.
- If there is already an issue that people are working on, you have a choice: you can contact the people working on the issue to see if they are looking for help, or you can find a different project to work on.
- If there is an issue but no one appears to be working on it, add a comment to the issue to say that you plan to make a patch.
- If there is not yet an issue about Drupal 9 compatibility, create one. Then add a comment to the issue to say that you plan to make a patch.
- Set up (but don't yet install) a local development site with:
- Drupal core -- the latest Drupal 8 development branch
- The Upgrade Status module
- The Upgrade Rector module
- Use Git to clone the repository for the project you're working on into the appropriate location in your development site, and check out the latest Drupal 8 development branch of the project (or the Drupal 9 compatible branch if there is already one created).
- Make a local branch in your Git repository to work on the fixes. (See the "Prepare the local repository" section of Making a patch for details on this step.)
- If the project has automated tests, follow the steps in this blog post about making it so that automated tests automatically fail if deprecated code is used (this will add a patch to the project).
- Install Drupal in your local development site.
- Generate a patch for all of the Drupal 9 compatibility fixes that can be done automatically: navigate in your site's Manage administrative menu to Reports > Available updates > Upgrade rector. Find your module in the list, run Rector to generate the patch, and save it to a file. Then apply and commit the patch in your local branch.
- Navigate in your site's Manage administrative menu to Reports > Available updates > Upgrade status. Find the project you're working on and check the checkbox. At the bottom of the page, click Scan selected to scan for compatibility errors.
- Edit your local codebase to fix the compatibility errors. After editing, return to the previous step and scan again. Repeat until there are no more errors. Some helpful hints for fixing compatibility problems:
- Most deprecation error messages include instructions on what class/function/method to use instead of the deprecated code.
- If the project still has Simpletest-based automated tests, they will need to be converted to PHPUnit tests. Instructions can be found on the Simpletest to PHPUnit documentation page and on this issue: #2735005: Convert all Simpletest web tests to BrowserTestBase (or UnitTestBase/KernelTestBase) (note that the issue was about Drupal core and might not completely apply to contributed projects).
- If there are a lot of tests to convert, you might start with a single test and get that working with PHPUnit first. Or consider making a separate issue for converting the tests.
- Watch out for
drupalPostAjaxForm()
-- any testing involving Ajax will likely need to be converted to a JavaScript-based PHPUnit test, which often requires a major rewrite of the test code.
- If the project has automated tests, run the automated tests locally and fix any errors you find. If the project does not have automated tests or they need to be converted and it's a separate issue, test the project manually to make sure it is working.
- Make a patch file containing all of your local changes.
- Upload the patch file to the issue. Add a comment explaining what you did. Change the issue status to Needs review, and save the issue changes and comment.