Background information
The Drupal 10 upgrade involves the following high level changes:
- The removal of the seven theme
- The removal of the stable theme
- The removal of the bartik bartik
- The removal of the color module
- The removal of the rdf module
- The removal of the quickedit module.
- The removal of the hal module.
- Possibly others
For WxT sites you'll want to uninstall these mostly unwanted theme and modules before upgrading. You must uninstall these modules and themes while in Drupal 9. This is because the uninstall code for these modules is not included in Drupal 10.
The Drupal 10 upgrade also removes deprecated APIs and libraries.
jquery.once is removed
jquery.cookie is removed
Generally you'll simpliy want to review your javascript console after upgrading to check for possible javascript exceptions related to this.
These changes are detected by and covered by the ordered list of steps outlined below. You may need additional support, do not hesitate to open a support request.
Other deprecated APIs that are included with D9 are removed from D10
This is covered by the ordered list of steps outlined below.
The Drupal 10 upgrade removes ckeditor4 from core, it is still available in contrib if you want to keep using it.
wxt5.0.0 includes the ckeditor4_codemirror module which if installed, allows you to continue using codemirror with ckeditor4 and does not interfere with the codemirror for ckeditor5. Open a support request if you have additional related ckeditor issues.
Before starting
- Upgrade your PHP to 8.1 before using composer
- Upgrade composer to a fairly recent version such as 2.4.x or 2.5.x before starting
- When needed, use the verbose flag -vvv to your parameters used with composer. Example: composer up -W -vvv
- add the --DEBUG flag to drush if you're stuck with drush
- Ensure that all of the drupal modules prefixed with the label "Lightning" or "lightning_" are uninstalled prior to starting the upgrade
Ordered list of upgrade steps
- FROM D9: Uninstall rdf, color, quickedit, hal
drush pmu rdf color quickedit hal -y; Uninstall seven drush theme-uninstall seven -y; Uninstall stable drush theme-uninstall stable -y; Uninstall bartik drush theme-uninstall bartik -y;export the new config related to the uninstalling drush cex -y;
- FROM D9: Double check and ensure that all lighting_* related modules have been uninstalled from your project. If you still have a lightning_* module hanging around you may need to do another Drupal 9 release to flush this out of your system completely in all environments. (lightning removal should have been performed automatically somewhere between wxt 4.2 and 4.4 but it is possible that someone may have accidentally re-included it in your project)
- MUST BE IN D9 - If you roll this series of commands in D10, it will skip the analysis of D9 to D10, it will focus on D10 to D11 which is not ready. Add and install the upgrade_status module
composer require drupal/upgrade_status;drush cr;drush en upgrade_status;
- MUST BE IN D9 - Use the upgrade status module code scanning tools to prepare custom modules for Drupal 10 (
drush us-a modulename1; drush us-a modulename2; # fix and scan, fix and scan until it passes scans as ready for D10
- STILL IN D9 - bring in upgraded custom modules as they are prepared (usually stored in my organisations git) - Upgraded modules will be expected to be compatible with both Drupal 9.5+ and Drupal 10.0/10.1+ so you can do this process while in Drupal 9
- Still in Drupal 9, review upgrade_status report in the report page and make recommended changes, while still in wxt4/D9, repeat steps 3, 4, 5.
- Still in Drupal 9 - Test everything and make sure your site still works after making the compatibility changes, if you've made all the changes and your wxt still works correctly after testing then move to step 7 and continue, otherwise return to step 3, 4, 5 and 6. Only continue to step 7 if you've scanned and upgraded ALL your custom modules and themes as outlined in the steps above
- Start of transformation to D10 - wxt4 locks some requirements (modules and patches) to D9-only versions of contrib, you must therefore upgrade the build from wxt 4.5.x to wxt 5.0.x (click here for detailed instructions)
- Continue transformation to D10 - Upgrading to wxt5 will often trigger patches to fail, look at the patch number, visit the corresponding drupal.org node corresponding to the failed patch, sometimes that patch is marked as fixed, check the dates of the fix and the date of the module version tag that is expected, if the fix happened before the release then you can remove the patch entry for this module from your composer.json, sometimes you'll need to update the link to the patch to a newer patch, read issues carefully related to patch issues. In some cases you may need to add a patches-ignore entry or report a new issue in the
wxt issue queue →
(please do create a new support issue if you're stuck here)
- Repeat step above until all drupal modules are D10 compatible. If the composer up -W error messages are telling you something you can find out more about a dependency by using
composer why drupal/modulename
- Continue editing composer.json until the above steps a few times as needed - See important notes about working around D10 compatibility with contrib
- Once you have fully dealt with each of the above steps core will be upgraded from D9.5.11 to D10.0.11
composer up -W and composer why dependencygroup/projectname helps you figure things out)
- run the update.php or
drush updb -y a few times until it's clean. Export the new upgraded configs into your project, review them carefully to make sure nothing savage is happening
- Example: I usually can figure out what gets busted just by exporting the config yml after an upgrade, this can lead to knowing what composer fixes to do for instance, if a module goes missing after the upgrade, and this , you can expect to happen in some cases and I've seen it
- testing and redoing the above steps until something decent comes out
- Typical project might take 4 or 5 days for all custom code and dependency unwinding to be figured out, this time estimation will drop and drop and drop as it becomes more and more easier to upgrade over time more and more dependency issues will be figured out for you however usually it takes some thought and good techniques to work through issues.
- success? celebrate
- stuck on something? open a support request in the
wxt issue queue →
Important notes about working around D10 compatibility with contrib
NOTE: please ignore or skip mentione of this workaround if all your contrib modules in your project are D10 compatible. Please follow the above ordered steps and only proceed to this if you've exhausted the normal options. This workaround is intended only for stubborn or neglected contrib modules and only do this if you've already checked for other D10 compatible branches of a contrib module that may work. Sometimes contrib maintainers incorrectly force a new branch for a new major release compatibility, this is annoying but is easier to deal with than doing the override approach described here:
Here are some light instructions on how to deal with certain contrib modules that may not be advertising to composer as D10 ready , such as how to add a drupaloverrides/projectname , the reason why composer works this way:
- composer update is ran before patches are applied, which is why you can't patch a module's composer.json/*.info.yml files and have those changes take effect. This is why we use drupaloverrides in composer, which point to a commit where the composer.json/*.info.yml changes are included.
- Might be interesting to look into Drupal's lenient composer endpoint for this -
https://www.drupal.org/docs/develop/using-composer/using-drupals-lenient... →
To see an example of drupaloverrides/projectname in action you'd have to look at this now outdated commit from drupalwxt/wxt as an example:
To be added to the "repositories" section of your composer.json:
{
"type": "package",
"package": {
"name": "drupaloverride/modulename",
"version": "dev-COMMIT_HASH",
"type": "drupal-module",
"dist": {
"type": "zip",
"url": "https://git.drupalcode.org/api/v4/projects/project%2Fmodulename/repository/archive.zip?sha=COMMIT_HASH"
}
}
}
- Replace modulename with the contrib modulename that is causing you fits where a D10 version is unavailable.
- Use a commit hash from either a merge request with D10 compatibility OR a commit hash that you want to use otherwise
- If you have a merge request hash with D10 compatibility, this is the easiest option as it won't require a patch entry.
- Otherwise, add the patch entry in composer.json that corresponds to drupaloverride/modulename
- Replace COMMIT_HASH placeholder mentioned above with the commit hash value, look in the git repository or merge request for this information, it usually is a hexadecimal value, you usually should only need the first 8 characters of this hexadecimal value.
- Then add the drupaloverrides/modulename entry into your composer.json requirement section, replacing the previous drupal/modulename value
example:
REMOVE THIS LINE:
"drupal/modulename": "^1.0",
REPLACE WITH THIS LINE:
"drupaloverride/modulename": "dev-COMMIT_HASH",
Now run:
composer up -W;
Dealing with lightning config and modules that may still be lingering in an incorrectly upgraded wxt-4.5.x
Skip this if your D9 system is already lightning free.
Only run this part if you still have lightning_ modules installed (check as follows)
drush pml | grep lightning -i;
Return to your D9 / wxt-4.5.x branch and schema, flush out lightning_ before proceeding if you for some reasons still have lightning in your configurations this command may automatically fix the issue for you.
drush eval "\Drupal::service('update.update_hook_registry')->setInstalledVersion('wxt_core', 8432);";
drush updb -y;
At this point you'll want to export the new configuration that has the lightning cleansed out.
Push this into your config
drush cex -y;
Review the changes, make sure it makes sense.
Expecting lightning_ modules to be uninstalled if they were not already uninstalled
Expecting wxt_ext_ modules to be installed if they were not already installed
Proposed resolution
See summary of upgrade steps and helpful instructions.
Remaining tasks
review and improve these steps.