Drupal 10 update
The distribution core team has gone through these steps to ensure as smooth of a transition as possible. If your site is up-to-date and using no additional dependencies you may be able to skip right to the update, but otherwise you’ll want to review these steps.
Resources
- Upgrading from Drupal 9 to Drupal 10 (drupal.org)
- Deprecated and obsolete extensions (drupal.org)
- mglaman/composer-drupal-lenient - can help install modules that do not yet have official Drupal 10 support.
Review important versions
Step through the distribution’s
important versions until you reach 9.2.13.0
. You should be running the latest Drupal 9.5.x before you begin the upgrade to 10.
Pre-checks
- CKEditor
- If any custom/contrib modules are used, CKE5 should likely be done AFTER your D10 upgrade
- Contrib checks will NOT be found in the next step, be sure to check these manually
- Dependency cleanup
- Modules not installed, but in composer.json should be cleaned up to prevent unwanted dependency issues in trying to update.
- Admin theme
- If your website uses a deprecated admin theme, you should migrate to the Claro theme and test the admin experience. If necessary you can keep the deprecated theme as a contrib package but that is not recommended and won’t be supported by the distribution.
Upgrade Report
- Install Upgrade Status
composer show drupal/core | grep versions
composer require --dev drupal/core-dev:[copy version above] --update-with-all-dependencies
composer require drupal/upgrade_status
drush en upgrade_status
- Run the report
/admin/reports/upgrade-status
- Check if the website is using custom CKEditor plugins with CKEditor Plugin Report
Keep / Kill
- Based from the report above, determine which modules (if any) could be removed without impacting the site
- From the remaining, review if the module
- Has a D10 ready version
- Has a D10 ready Fork/Patch
- mglaman/composer-drupal-lenient allows you to install outdated modules without using forks!
- Has been abandoned
- Itemize based on the above with notes of efforts to continue using the modules
Custom modules and themes
- Run custom modules and themes through
drupal-check and
phpcs and fix issues
- Some common issues:
- Remove jQuery dependency from the once feature
- Migrating dependencies on core jQuery UI libraries
- Functions file_create_url() and file_url_transform_relative() are deprecated
- Access checking must be explicitly specified on content entity queries
- drupal_get_path() and drupal_get_filename() have been deprecated in favor of extension listing services
- Preparing for Twig 2 in Drupal 9
- Some common issues:
- Search for
hook_field_widget_form_alter
,hook_field_widget_multivalue_form_alter
,hook_field_widget_WIDGET_TYPE_form_alter
andhook_field_widget_multivalue_WIDGET_TYPE_form_alter
. These hooks have been deprecated in Drupal 9.2 and not available anymore in Drupal 10. Streamline field widget hooks
Patches
- Review patches in
composer.json
. Review any that are no longer applying or may be duplicated by the distribution. - Carefully review and re-roll custom patches.
Update
At this point you should be ready to update to the latest version of the distribution:
- Edit the
ycloudyusa
version in your project rootcomposer.json
:"ycloudyusa/yusaopeny":"^10.3",
- Run
composer update
- If errors occur, review the conflicts, check out the known issues, and attempt to resolve them.
- Re-run the previous steps until they complete successfully
- Run
drush updb
, review the updates, and run them.
Smoke tests
We recommend reviewing critical functionality after the update to ensure any custom functionality still works.
Troubleshooting
Composer issues
Composer can be … tricky. To resolve composer conflicts:
- If specific modules conflict, try requiring them directly to get more information about the conflict.
- Make good use of composer why and composer why-not
Update hook conflicts
If you run into an error like this:
> [notice] Update started: y_lb_update_9011
> [error] Configuration core.entity_view_display.node.lb_event.featured depends on the core.entity_view_mode.node.featured configuration that will not exist after import.
you may be able to resolve it yourself.
Breaking down the error message:
core.entity_view_mode.node.featured
is missing, which is blocking y_lb_update_9011 from installingcore.entity_view_display.node.lb_event.featured
- We need to figure out where
core.entity_view_mode.node.featured
should be coming from, so we can search our code for that.- Use the “Find in files” command in your IDE to search
docroot/modules
, or - from the command line:
╰─ grep -rI "core.entity_view_mode.node.featured" ./contrib/ws_event/config/optional/core.entity_view_display.node.lb_event.featured.yml: - core.entity_view_mode.node.featured ./contrib/y_lb_article/config/optional/core.entity_view_display.node.article_lb.featured.yml: - core.entity_view_mode.node.featured
- Looking at those files in the codebase, they are identical, so we could manually import them from either module. Let’s do it.
- Use the “Find in files” command in your IDE to search
Add an update hook to your own custom module like this example.
// This goes in mymodule.install as the next update hook. // Increment the number accordingly. function mymodule_update_9000() { $path = \Drupal::service('extension.list.module')->getPath('ws_event') . '/config/optional'; /** @var \Drupal\config_import\ConfigImporterService $config_importer */ $config_importer = \Drupal::service('config_import.importer'); $config_importer->setDirectory($path); $config_importer->importConfigs([ 'core.entity_view_mode.node.featured', ]); }
Use hook_update_dependencies to ensure this new update runs before the failing one.
// This also goes in mymodule.install. function mymodule_update_dependencies() { $dependencies['y_lb'][9011] = [ 'mymodule' => 9000, ]; }
Re-run
drush updb
.If you run into other missing configs, add them to the list to be imported in
update
hook and re-runupdb
.Consider backporting your customization which led to the challenge of doing this upgrade in order for it to be covered and tested by distribution developers.
Planning for Drupal 11
After successfully upgrading to Drupal 10, you may want to plan for Drupal 11 in the future.
See the Drupal 11 Migration Guide for:
- Drupal 11 beta status and Q4 2025 stable release timeline
- New features and breaking changes in Drupal 11
- Known issues (including jQuery 3.x compatibility)
- Prerequisites and upgrade steps
Note: Most YMCAs should remain on Drupal 10 until the stable Drupal 11 release in Q4 2025. Drupal 10 is supported until December 9, 2026.