Drupal 10 update

The update from Drupal 9 to 10 is easier than some, but still comes with some challenges.

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

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

  1. CKEditor
    1. If any custom/contrib modules are used, CKE5 should likely be done AFTER your D10 upgrade
    2. Contrib checks will NOT be found in the next step, be sure to check these manually
  2. Dependency cleanup
    1. Modules not installed, but in composer.json should be cleaned up to prevent unwanted dependency issues in trying to update.
  3. Admin theme
    1. 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
    • fin composer show drupal/core | grep versions
    • fin composer require --dev drupal/core-dev:[copy version above] --update-with-all-dependencies
    • fin composer require drupal/upgrade_status
    • fin 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
    • Has been abandoned
  • Itemize based on the above with notes of efforts to continue using the modules

Custom modules and themes

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 root composer.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 installing core.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.

  1. 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',
    ]);
}

  2. 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,
  ];
}

  3. Re-run drush updb.

  4. If you run into other missing configs, add them to the list to be imported in update hook and re-run updb.

  5. 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.

Last modified September 20, 2023: Apply suggestions from code review (f866dc462)