Creating or updating Drupal 10 compatibility patches

Prerequisites

• Drupal 9 development environment is prepared. See instructions.
• Account on drupal.org

The instructions below were tested with DDEV. They should mostly work with other setups if you replace ddev composer and ddev drush with the appropriate commands.

Finding the right issue

Pick an issue for testing using one of the methods described in the Getting Started guide. Follow the documentation below to further validate if the issue requires patch creating or updating.

Checking dependencies

The module/theme you found may be dependent on another module/theme that isn't compatible yet which will make it more challenging to test. Check the dependencies for this if you don't want this complication.

Read the comments!

If the update bot thinks that it has fixed all the problems, then there is no job for us in this module! Go and find another issue or proceed with patch testing workflow instead: Testing compatibility patches on Drupal 10.

If instead, the update bot thinks that there are problems it cannot fix, then it will say something like:

 This patch does not update the info.yml file for Drupal 10 compatibility.

It means we've found a good issue to work on! Example: https://www.drupal.org/project/module_filter/issues/3297692#comment-1461...

However, before going too far, read the comments on the issue. Maybe someone else beat you to it!

Assess a module

For example, let’s install the Dialogflow (Api.AI) Webhook module.

ddev composer require -W drupal/api_ai_webhook:2.x-dev

Then go inside the module directory and switch to the latest dev version of the module.

1. cd web/modules/contrib/module_name
2. git checkout <dev_branch>

Then install the module and any of its sub-modules on your local site:

ddev drush pm:install api_ai_webhook

Assess the module with Upgrade Status

Is this Drupal 9 module ready for Drupal 10? Let's find out:

ddev drush upgrade_status:analyze api_ai_webhook

You can also analyze a module from Upgrade Status friendly web UI available at /admin/reports/upgrade-status page.

You will see a bunch of Drupal 10 compatibility errors, mostly due to deprecations.
Luckily for us, Project Update Bot has already scanned this module and left a patch addressing some initial compatibility issues. You can benefit from the initial work done by the bot by applying its patch. Common Composer workflow can be used.

Run again Upgrade Status analyzer. Now you should see fewer errors.

Make the module Drupal 10 ready

Now it's your turn. Follow instructions from the Upgrade Status report in order to fix all pending issues.

Make sure the module is installed, so Upgrade Status can assess libraries deprecations.

Create/Update Drupal 10 compatibility patch

Upgrade Status doesn't report any more issues? Congratulations! You made the module Drupal 10 ready.

Now let's submit your contribution!

If you're not yet familiar with git commands - don't worry! You can do this directly in a web browser, without any additional tools! Just press the "Create issue fork" button, click on the created fork link to open GitLab interface, find needed file there and open it, click on the blue "Edit"(or "Open in Web IDE") button, make changes (you can copy-paste the changed code from your local files) and commit them. That's all!

And for more advanced git users Drupal.org provides two ways:

1. Creating a fork for the issue using the "Create issue fork" button, clone the fork locally, make and submit changes, and create a Merge Request using Drupal.org interface. More detailed information: Creating issue forks and merge requests.

2. Creating a patch file and attaching it to the issue:

cd web/modules/contrib/module_name
git diff > module-name-d10readiness-1.patch

New to Drupal patches? Check the more detailed instruction: Making a patch.

3. Creating an updated version for a patch that already exists for an issue:

A patch interdiff is a text file which highlights the difference between two versions of a patch for an issue. Using interdiff is a best practice that saves time and reduces tedium for reviewers by allowing them to focus on just the changes introduced in patch iterations.

Follow this link for more detailed guidance on how to create interdiff patches.

Leave a comment on the d.o issue

In all cases

• Mention anyone you were working with.
• Give details about how you tested and/or reviewed.
• Fill out the “Attribute this contribution” section: are you volunteering your own time or is someone sponsoring your work?
• Tag the issue with an appropriate tag (use existing tags please), e.g. Drupal 10 porting day and Drupal 10 compatibility

The module has got already a Drupal 10 compatibility issue

• Leave a comment explaining what you've done (see below for an example)
• Upload your patch
• Change the status to Needs Review if the latest patch has not been committed. If the latest patch has been committed, set the status to Active. Do not change the status to "Reviewed & tested by the community" unless you are the maintainer of this module and you do not wish to accept further patches from Drupal Update Bot.
• Celebrate.

The module does not have a Drupal 10 compatibility issue

• Create one (see Useful links for further info).
• Follow all steps from the section above.

Sample comment

Here is a draft of the comment:

I tested this issue with @benjifisher and @mattlibby

What worked:

1. I was able to assess the module code with Upgrade Status.
2. I was able to apply the patch provided by Project Update Bot.
3. I was able to fix Foo/Bar/ALL issues

What did not work:

1. I got an error when I tried to do X, Y, Z. The error was: "Error: Class "Drupal\Core\Whatever" not found in include() (line 28 of /var/www/html/web/modules/contrib/module/whatever.php)"
2. Can't find the change record for reported issue "Call deprecated method FooBar()".
3. Any other issue

Next steps

You have now two options:

1. Go and test the compatibility of your patch on Drupal 10. It will require a similar setup, but running Drupal 10.
2. Find a new issue/module and start again!

 Useful links

• Creating or updating an issue report
• Patch and merge request guidelines
• Making a patch
• Creating issue forks and merge requests