Acquia Support’s Guide for Upgrading to Drupal 10

Even though Drupal 9 is officially EOL as of November 2023, Acquia Support can still help you. This document offers some guidance and clarifies our policies around the upgrade process. 

Clarification of Acquia's stance on Drupal 9 End-of-Support

Many customers are moving to Drupal 10 since the general Drupal community will stop providing security and other updates to Drupal 9.

From Acquia's messaging around our Drupal 9 EOL, the statement:

"Acquia will no longer provide support for Drupal 9.x applications." 

… may be confusing and could use some clarification.

It does NOT mean Drupal 9 would stop working on the Acquia platform. It does NOT mean you are unable to file Support tickets for Drupal 9 applications. 

Here’s a more detailed explanation:

• By "Support" we are referring to our overall policies and strategy, and not exclusively to software or platform components and whether they are compatible with Drupal 9.
• The Acquia platform won't immediately change anything (like MySQL version, available tools or packages, etc.) that would prevent customers from running or even installing Drupal 9.
• This means that, immediately after our D9 end of support deadline, existing applications should continue to function without issues.
• However, we strongly recommend updating to Drupal 10 since:
  • Acquia will eventually implement changes to its platform that will only be tested against supported Drupal versions (7 and 10). 
  • It is likely these future changes won't negatively impact Drupal 9 applications either, but if they do, we may not be able to help. 
  • Drupal 9 itself will stop receiving attention from the community, meaning no more security patching, contributed modules may become incompatible with it (if they have not properly declared their Drupal version requirements), etc.
• If you need Acquia Support’s help for a D9 site, we can still help,

What if I can’t upgrade right now?

As mentioned above, D9 should still remain compatible with the Acquia platform for some time.

The most important thing is to have a viable plan to upgrade as soon as possible. 

Therefore, if you are on D9 and find that some critical functionality depends on code that does not yet work with Drupal 10 (for example, if contrib or custom code isn’t compatible with D10 yet), you might consider:

• Update your D9 site and contrib modules to the newest available code, and keep it as your production site in the short term, while preparing for alternatives to doing your D10 upgrade.
• Plan a phased D10 upgrade where you could temporarily remove some site functionality, and/or have a worse-performing site, etc. and continue developing and/or working with the Drupal community to finish development of any D10-incompatible or problematic code.

What are some good resources that can help me with my Drupal 10 upgrade?

• Acquia Dev Blog: What to do about Drupal 9's end of life in November 2023
• Acquia training: Updating Drupal Core 

What are some pitfalls to avoid when upgrading?

Here are some things to consider when upgrading:

Upgrade in steps

Customers who skip sequential versions (e.g. jumping from Drupal 9.4.x to Drupal 10.1.x) sometimes encounter more challenges than they would otherwise. So, try to update sequentially. 

For example, first upgrade to the most recent Drupal 9.5.X version (along with all your modules!). After that, upgrade from 9.5.x to 10.0.x; then upgrade to 10.1.x (later, if needed!). 

Don’t try to upgrade all the things at once. Don’t rush it, steady forward progress is better than no progress.

Note that the upgrade from Drupal 10.0 to 10.1 introduces further API changes (example 1, example 2). You may need to again check contrib modules for issues, test/apply patches or upgrade to later versions. Consider working with the Drupal community to accelerate fixes that everyone can benefit from!

Sites using CKEditor 4 should upgrade to CKEditor 5 in Drupal 9.4 or 9.5 before updating to Drupal 10

Most Drupal sites using CKEditor 4 should upgrade to CKEditor 5. Upgrading from CKEditor 4 to 5 is a manual process, because it requires human supervision. We recommend reading our article:https://dev.acquia.com/tutorial/upgrading-ckeditor-5

However, there is the option of keeping CKEditor 4 on Drupal 10 (although it is also being EOL’d soon). Read https://www.drupal.org/docs/core-modules-and-themes/deprecated-and-obsolete#s-ckeditor for more information.

Contrib modules may have advertised compatibility with D10 but may have bugs

Because changes were introduced in Drupal 10, existing code for D9 may have not been tested completely under D10, and could run into yet-unknown problems. If you run into any problems, you must upgrade any contrib modules as a first step (since they may include bugfixes). If still experiencing problems, consider rolling back your site changes to a known-working point until a patch or fix becomes available.

Thus, we recommend first updating and testing all modules on Drupal 9.5.X first before thinking of migrating to D10.

Additionally, minor (a.k.a. “feature”) Drupal version upgrades (i.e. 10.0 to 10.1) can introduce changes that can cause erratic/buggy behavior in module code. Usually, Drupal APIs are not meant to change between minor versions, but that doesn't always mean that every module will continue to work seamlessly. Therefore, you should always test thoroughly and be prepared for minor problems that may arise.

Drupal 10 requires PHP 8.1 or higher.

You will need to think about upgrading the PHP version at around the same time as you upgrade Drupal. We recommend doing this while you are testing on the latest Drupal 9.5.X core and modules. 

Note that modules may also need to be tested against the newer PHP version.