1. Web Theme User Guide
  2. Documents
  3. Migrate to Drupal 10 Steps
Book: For Developers
Last Updated: 02/09/2024 - 13:27

Migrate to Drupal 10 Steps

This step by step guide helps site owners navigate the steps to a successful migation from Drupal 9 to Drupal 10. If you are a developer responsible for migrating department sites, check out our Migration Resources page for more information on the Pantheon documentation we are using as well as tools and modules to get your site Drupal 10 ready.

Pre-Migration Work

  1. If a site is still in Sandbox, consider whether it should be migrated to D10 or deleted and rebuilt with the new D10 Web Theme.
  2. If you have custom modules or are using a custom theme other than "UCSB Web" or "UCSB Web Sub", run the Upgrade Status module and apply the necessary code changes to address any compatibility issues with Drupal 10. Deploy changes to DEV/TEST/LIVE
  3. If you are the developer performing the migration, you must be the UIC as well. One of the final migration steps is to switch the upstream from D9 to D10. The only way to run this command is if you are the UIC for this site. If needed, our office can assist with this step - please reach out to webtheme@brand.ucsb.edu
  4. Apply any pending updates (both from the upstream and composer updates) to DEV/TEST/LIVE
  5. Run update.php and fix the errors if any
  6. Ensure all environments (Dev/Test/Live) are in sync.

 

UIC Emails

  1. If you are a User In Charge (UIC) of more than 5 Web Theme sites, our office will be in touch to run through the migration steps and timeline.
  2. If you manage 1-4 Web Theme sites as a UIC, our office will coordinate the migration. Keep an eye on your email for further instructions from us.

Migration Steps

Creating a Multidev Environment with D10 Code

We will execute a migration script on your site. This script will install a Drupal 10 codebase within a multidev environment ("d10"). After cloning the D10 code, the script analyzes the configuration for websites and proceeds by copying the custom code and configuration for your site, if necessary. Once completed, we will promptly notify you for review.

Please note: The migration script will disable Autopilot. Once you complete the migration process, you will need to enable it manually.

d10 multidev is ready screen

The following process typically takes 30 - 60 minutes, depending on the size and complexity of the site. While we don't expect any downtime, we recommend coordinating with your content editors to choose a migration timeframe when site activity is minimal.

Review the D10 Multidev site

Please note: On the Pantheon Dashboard for the 'd10' multidev, you will see many pending updates. DO NOT make any updates at this time (those are Drupal 9 updates.)

Thoroughly review the d10 Multidev site to ensure its functionality:

  • Review Custom Theme and Custom Module(s) to make sure they are functioning
  • Try updating a page and saving
  • Check webforms and confirmation emails
  • Review admin reports for errors: logs, status reports

Once you have confirmed that the site works in the multidev, proceed with the next step.

Deploying to the Main Dev Branch

Note: The following Git changes should happen locally first.

  1. Backup Dev environment of the Drupal 9 site.

  2. Set up local dev environment using Git Clone from the Pantheon Dashboard.
    Clone with Git screen

  3. Change directory to the cloned repo.

  4. Checkout the multidev branch locally, git checkout d10

  5. Retrieve the most recent commit hash from the local branch: git log --format="%H" -n 1.

    1. This will give you a commit hash like fd3636f58f5b275b998bb1c9267bff8808353840.

  6. Reset the master branch to match that commit using the hash then force push that to the Dev environment:
    git checkout master
    git reset --hard fd3636f58f5b275b998bb1c9267bff8808353840 (*replace the hash with the one you retrieved)
    git push --force origin master

  7. Now the site's Dev environment has a Drupal 10 codebase. Go to the Pantheon Dashboard and make sure that the workflow has completed.
    Pantheon Dashboard Workflow screen

  8. Clear the site cache and update the database.

    1. terminus drush site.dev cc drush

    2. terminus drush site.dev updatedb
      terminus drush site.dev updatedb
      We recommend running these at least twice to ensure all the changes are made. When updating the database, there will be a large number of changes.
      Drush Updb command

  9. Log in to the DEV site and check the status report, /admin/reports/status
    D10 Status Report screen

  10. Go to /admin/config/search/simplesitemap and click the button to regenerate the sitemap. Clear cache when done.
    Simple XML Sitemap screen

Change Upstreams

Note that the User in Charge, Site Owner, or Organization Administrator can change the Upstream. Contact webtheme@brand.ucsb.edu if you need assistance.

  1. Set the site to use the Drupal 10 - UCSB Web Theme Upstream
    terminus site:upstream:set <site-name> 08a2bf56-1687-448c-b1f7-3890dd5ebab9
    Terminus screen of changing upstream
  2. Go to Pantheon’s Dashboard and verify the upstream was updated
    Pantheon Dashboard shows the site is using Drupal 10 Upstream
  3. Apply any pending updates

 

Deploying to the Test Branch

Deploy as usual:

  1. Backup Test

  2. Use Pantheon’s Dashboard to deploy

  3. Verify the site works fine and regenerate the sitemap

Deploying to Live!

Deploy as usual:

  1. Backup Live

  2. Use Pantheon’s Dashboard to deploy

  3. Verify the site works fine and regenerate the sitemap

Reactivate Autopilot

The migration script disables Autopilot. Reactivate it accordingly.