Testing compatibility patches on Drupal 10

Prerequisites

• Drupal 10 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 is available for testing.

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 it will say so and the patch will update the .info.yml file.

If the update bot thinks that there are problems it cannot fix, then it will say so and the patch will not update the .info.yml file.

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

Run DrupalCI with the patch against Drupal 10

Run DrupalCI for the patch against PHP 8.1 & MySQL 5.7 for Drupal 10.0.x development.

1. Do this by clicking the "Add test/retest" link below the patch name. 
2. Check the Custom parameters checkbox
3. Select PHP 8.1 & MySQL 5.7 for Environment
4. Select Drupal 10.0.x : Drupal 10 Development for Core
5. Press Queue

Drupal 10 run fails with: D10.0 Composer require failure

If you are not comfortable making this change, ask for help in Slack so one of the mentors can help out.

When the run fails with this error the module will need to have a change in composer.json for the runner to pick up those changes. If the module has no composer.json you can add an empty one like the one below temporarily:

{
    "name": "drupal/[MODULENAME]",
    "type": "drupal-module",
    "license": "GPL-2.0-or-later",
}

This should make the tests run. Please comment on the issue that the composer.json changes should not be committed.

Install a module to test

For example, let’s install the Pathauto module.

Add the module in the drupal-lenience config list

By default Drupal modules would not have Drupal 10 compatible releases, Hence you would not be able to download them via Composer. To allow that add the module drupal-lenience composer config section. Refer to https://github.com/mglaman/composer-drupal-lenient for details.

ddev composer config --merge --json extra.drupal-lenient.allowed-list '["drupal/pathauto"]'

If your module is dependent on another contrib module that doesn't have d10 compatible release, the above command will need to run for that module as well.

Try installing the dev version

ddev composer require -W drupal/pathauto:1.x-dev@dev

Note that the command above specifies a version 1.x-dev after the package name. You can find the correct dev version for your module in the sidebar of the D10 compatibility issue. If the version starts with 8.x-, remove this prefix and keep the rest:
Version specified in the issue: 8.x-1.x-dev
Version for Composer: 1.x-dev

Install and patch the dev version

Open the automated D10 compatibility issue for your module. Example for Pathauto: https://www.drupal.org/project/pathauto/issues/3289029

Find the link to the patch and add it to composer.json under extra.patches as below:

Edit composer.json:

"extra": {
    "composer-exit-on-patch-failure": true,
    "drupal-lenient": {
        "allowed-list": [
            "drupal/pathauto"
        ]
    },
    "patches": {
        "drupal/pathauto": {
            "3289029: Automated Drupal 10 compatibility fixes": "https://www.drupal.org/files/issues/2022-06-16/pathauto.1.x-dev.rector.patch"
        }
    },
    "patchLevel": {
    "drupal/core": "-p2"
},

Ensure there is an entry under extra.drupal-lenient  for your module: see above.

As always, the JSON format is finicky. Be careful about balancing quotation marks, balancing braces, and adding commas (but not after the last item in a list).

Re-install the dev version of the module to apply the patch:

ddev composer require -W drupal/pathauto:1.x-dev@dev

This still will not work because the Pathauto module depends on the Token module and the Token module does not have a release compatible with Drupal 10. It looks like the dev version of Token is compatible, so install that:

ddev composer require -W drupal/token:1.x-dev@dev

Now, re-try the command to install Pathauto, and it should work. The composer should install the module and apply the patch.

Confirm that you have installed the version you think

ddev composer show drupal/pathauto

Check the versions line.

Enable the module/theme

ddev drush en pathauto

After enabling, check the Drupal logs to see if there are errors or warnings.

Test the module/theme

Sometimes the module/theme can be enabled cleanly, but still has issues when you try to use it. Opening the module/theme's settings page successfully does NOT confirm its Drupal 10 compatibility!

Ideally, you would know how to use the module/theme and you can actually test it is working on Drupal 10. If you do not know how to test it, just add a comment that you did the above (see example comment below) but that you didn't test the module/theme.

If you are able to test the module/theme, make sure to add notes with your testing steps when adding your comment.

After testing, check the Drupal logs to see if there are errors or warnings.

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. Simply saying "it works" or a screenshot of the settings page (or Drupal status report) is not helpful! Describe all you've done, all features you covered, and the scenarios you went through: the more the merrier.
• 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 patch works

• Change the status to Reviewed and Tested by the Community (RTBC).
• Celebrate.

The patch does not work

• Change the status to Needs Work (NW).
• Say what worked and what did not work.
• Copy in the error message, if there is one (but not the whole stack trace).
• Optional: find the change record (CR) that describes the breaking change. https://www.drupal.org/list-changes/drupal
• Celebrate. You have made a big step forward!

Sample comment

Here is a draft of the comment we added for the Pathauto module:

I tested this issue with @benjifisher and @mattlibby

What worked:

1. I was able to install pathauto using the mglaman/composer-drupal-lenient (https://github.com/mglaman/composer-drupal-lenient) composer plugin.
2. I was able to enable the module.

What did not work:

I got an error when I tried to add a pattern:

1. Navigate to Admin/Configure/Search and Metadata/URL aliases
2. Navigated to the Patterns tab (/admin/config/search/path/patterns)
3. Clicked “Add Pathauto pattern”
4. Selected the “Content” pattern type
5. Added a label
6. Clicked the “Save” button and this triggered the error that we found in the logs.

Error: Class "Drupal\Core\Plugin\ContextAwarePluginBase" not found in include() (line 28 of /var/www/html/web/modules/contrib/pathauto/src/Plugin/pathauto/AliasType/EntityAliasTypeBase.php)

The change record is Deprecate passing context
values to plugins through configuration and remove ContextAwarePluginBase
(component & core) in favor of a new trait

The patch is not working because a class extends ContextAwarePluginBase, which has been deleted from Drupal 10.