Cloud Platform
Top 10 Steps to Upgrade to Drupal 10
Drupal 10 is here! What are you waiting for? It's time to upgrade! But... before you do, here are my top ten things to do before you pull the trigger. Remember, the Drupal 10 update is easier than ever...assuming you're ready for it.
Just like the Drupal 8 to 9 upgrade a few years ago, the main difference between Drupal 9.5 and Drupal 10.0 is the removal of all the deprecated code. What does that mean? If you've got any PHP code that relies on a function that no longer exists, your site is going to white screen and throw fatal errors. Fun, right?
Thankfully there are a number of tools you can download and run on your site right now that will tell you if you are compatible with Drupal 10 or not. My personal recommendation is the Upgrade Status module.
Warning: I would not recommend committing any configuration or composer changes that actually leave Upgrade Status in your codebase or enabled at this point. We'll cover this more below in #3.
Once you have your Upgrade Status report, it's time to start refactoring your code. Hopefully you don't have too much to change, but the bottom line is you cannot do any sort of dry run or actual upgrade to Drupal 10 until you've remediated all of your custom code. Many of the deprecation changes end up being quite minor (replacing one function / method with another). However, don't take these for granted. Even one word replacements can break a website if not handled and tested properly! Most Drupal API changes have automated coverage in drupal-rector, Upgrade Status will tell you when to use that to speed up your work.
What about remediating the contributed updates?! Hold on hold on, we'll do that in a moment. But if we're going to run a bunch of module updates, let's also do the PHP 8.1 update. Some modules may also be incompatible with PHP 8.1 so we'll want to try and knock this out at the same time.
Remember, all environments must eventually be updated to PHP 8.1 for Drupal 10. For this exercise we'll start with your local environment / Cloud IDE. But as we progress, you'll also need to update any CI/CD environments, your teams' locals, and all cloud environments.
Did you know you can add PHP as a dependency in composer as well? It's quite simple and will also help weed out incompatible dependencies.
"require": {
"php": ">=8.1"
}
Once in composer, you can composer update php --with-all-dependences just like anything else.
Now let's update all of those contrib modules to be both D10 and PHP 8.1 compatible. This is best accomplished with composer. Upgrade Status will help you understand which modules have compatible versions and which don't. Thankfully, many many more modules are D10 compatible right now than were D9 compatible at the same point in the release cycle.
Acquia provides some fairly in depth reporting on the readiness of the community here on dev.acquia.com, you can check that out here.
Keep in mind that there may still be modules that are not D10 compatible today. This could block you from updating unless you can help get those projects ready (or you remove them from your project). If you need a contributed project that is not yet ready, Upgrade Status will help find the existing issue or issues where discussion about required fixes is happening. You can composer require an incompatible project with mglaman/composer-drupal-lenient and apply needed patches with cweagans/composer-patches. Make sure to provide feedback to project maintainers about patches in the issues.
Let's be honest, this "probably" already happened when you updated to PHP 8.1 but it's worth calling out separately. If you're using other tools (e.g. Acquia BLT) that are composer required into your project, you need to make sure that all of these are also compatible with PHP 8.1 and/or Drupal 10.x. Otherwise, these tools will block you from doing the update.
It's a little confusing, but Drupal 10 will only work with Drush 11. Acquia provides up to Drush 10 on our hosting platform but we do not provide Drush 11 as Drush 11 must be installed via composer in your codebase. So, if you're already using Drush in your project via composer, all you have to do is upgrade to Drush 11 with drush/drush: ^11. However, if you aren't, you'll need to add drush 11 with composer require drush/drush ^11.
Drush 11 requires PHP 8.1 (good thing we already did that) and Symfony 6.x components (which also require PHP 8.1). Previous versions of Symfony (4 and 5) are PHP 7.4 and 8.0 compatible, hence the jump.
As of right now, Drupal 9.5.0 is out. You don't technically have to be running the most current 9.5.x to hit Drupal 10, but 9.5.x is the only branch still receiving bugfixes. While 9.4.x can also be used to update, older versions of Drupal 9 do not have a supported upgrade path.
Now this one may be a little counterintuitive, but go with me. Upgrade Status currently works for Drupal 9.x. It does not work with Drupal 10.x yet. So, believe it or not, you now need to remove Upgrade Status from your code before you can continue. This is why I warned you above in #10 not to leave Upgrade Status installed!
I usually assume that major upgrades will fail the first time I try them. I am a strict follower of Murphy's Law (if it can go wrong, it will go wrong) so having a thorough plan for testing in a safe space so that you can constrain any explosions is only going to make your life easier. Ideally, you'll do several dry runs. For me, I do this locally, in CI/CD, and then in my dev environment at minimum before I even think about pushing a major version update into production!
Also, during the dry run, this is a good time to find out if there are any additional packages that might be blocking or controlling your update. A few common ones are...
If you still can't get a composer update drupal/core --with-all-dependencies to resolve into Drupal 10.x, you can always run composer why-not drupal/core 10.0 to get some insight into what in your composer dependency tree still requires something other than 10.x.
Finally, when you're ready to do the deployment into your production environment, make sure you have a snapshot of your code and database. Assuming you did dry runs in other environments (and they succeeded) then you should be clear to continue with the update. But... if you have backups, you'll thank me the one time you have a problem.
So that's it! A pretty simple list (and if you did the Drupal 8 to 9 update it should look very familiar). Good luck in your updates!
Cloud Platform