Start a Drupal 9 Readiness To-Do List using Upgrade Status

I recently wrote about using drupal-check and drupal-rector to assist in upgrading your Drupal 8 code so that it's ready for Drupal 9. And in the comments for that post Gabor mentioned that I should check out the Upgrade Status module. So I spent a little bit of time playing around with it and here are my notes so far.

It's AWESOME, and you should try it. Thank you to everyone that's been working on it.

TL;DR: Upgrade Status generates a report that serves a sort of checklist to help you determine whether or not your site is ready to be upgraded to Drupal 9. It packs a lot of useful information into a single report. And it's worth taking the time to install it on a copy of your Drupal 8 site and seeing what it has to say.

Behind the scenes Upgrade Status performs the following checks, and probably more:

  • Are you using the latest version of the module?
  • PHP code deprecation via drupal-check
  • Check Twig templates for calls to deprecated functions
  • Check {MODULE}.libraries.yml files for deprecated dependencies
  • Analyze hook_theme implementations
  • Verify composer.json and {MODULE}.info.yml files are Drupal 9 compatible
  • Does the Drupal.org project provide a Drupal 9 upgrade roadmap?
  • Probably more...

Then it pulls this all into a nice visual report like the example below, complete with links to both issues and documentation to help you best resolve the issues it finds.

Screenshot of upgrade status report described in detail in this post.

Hosting environment report

The report starts by listing hosting environment compatibility. It's worth noting that you'll probably want to install the module and generate these reports on a non-production environment, and that these indicators are for the current environment. But it does give you an idea of what to look for on your production environment. Namely, are PHP, MariaDB (MySQL), and Apache up-to-date enough to be compatible?

Current requirements (in addition to what's already required for D8) are listed here: Environment requirements of Drupal 9 (drupal.org).

Custom code report

Then there's a section that reports on your custom code. Anything that's in this list is your responsibility to upgrade. So if you're looking for next steps, this is a good place to start. If you click the "X errors, Y warnings" link for any project it'll open a modal window with a detailed report of what needs to be done. And in most cases link you to the relevant change record, or documentation page.

Screenshot of detailed report for Drip module showing a single warning about missing code and a link pointing to where you can find more information.

Contributed projects report

This is followed by a report on all the contributed projects you have enabled. Note that Upgrade Status only scans enabled projects. This list provides the same link to see a detailed report as above, and a bunch of additional information as well. It'll indicate things like:

  • The Available update column will show either Up-to-date or a version number. If there's a version number this means you're currently using an out-of-date version of the project and should upgrade. Note that if this column lists N/A for everything make sure you've got the Update Manager enabled and that it's run a status check recently. If not, you can trigger one manually at Reports > Update status.
  • "Consumers >= 8.x-1.11 is compatible with Drupal 9.": There's a newer version of the module than the one I have installed and it is Drupal 9 ready. Learn how to update a module (or theme)
  • Some modules, like for example Recurly in the example above, provide detailed Drupal 9 roadmaps (Note: maintainers, you can add this via your project page!), that help indicate where things are at.

Try Upgrade Status on your site

Install it (I recommend you do so on a development environment) using Composer:

composer require 'drupal/upgrade_status:^2.0'
drush en upgrade_status -y

The project page mentions the optional Composer deploy, and Git deploy, modules. If you've got projects installed via Composer where the required version is a -dev version (e.g. "drupal/migrate_source_directory": "1.x-dev" or projects that have been added by cloning their Git repository, then you can install the respective optional helper module to ensure Upgrade Status can find the information it needs for those projects.

The reason you need these is because modules installed via either Composer (in some cases) or via Git don't contain the version key in their *.info.yml files that gets added automatically by Drupal.org. Upgrade Status uses this to determine what version of the module you're currently using.

Anyway, if you use Composer to manage your project adding Composer Deploy won't make things any worse and may make them better:

composer require drupal/composer_deploy
drush en composer_deploy -y

Note: After installing have Drupal run its Update status checks again (Reports > Update status).

Scan your projects

You need to tell Upgrade Status to scan your project(s) before it can provide detailed reports. This can be done either by navigating to the report page at Reports > Upgrade status then checking the box for each project you want to scan and pressing Scan selected at the bottom of the page.

Or use one of the included Drush commands. Because the module caches the results of each scan you can use Drush to run a scan and still view the detailed report via the module's UI.

What next?

I think the biggest win for me using Upgrade Status is that it helps illustrate where I should be spending my time. Once my custom code is ready to go I can pretty quickly see that state of the different contributed projects I'm using, and which ones are most likely to benefit from my helping out.

In my case the Group module is super important to what I'm doing, so I'll start by seeing what if anything I can do to contribute to getting that module Drupal 9 ready first. Simple OAuth is also very important so I should update to the latest version of that and run these checks again.

I also look at this list and think, I'm not using Configuration Installer, so I should remove that. And, in my use case I could switch to using the Drupal core Media Library instead of Entity Browser and Inline Entity Form which would remove those (plus their dependencies like dropzonejs and Entity Embed) from the list of things I need to worry about.

Here's some questions to ask yourself when reviewing the report provided by Upgrade status:

  • Do I know what the minimum hosting requirements are, and what do I need to do (if anything) to prepare my hosting environment?
  • Are there modules in this list that we're just not using at all and can be disabled and removed?
  • Are there modules that we might want to consider replacing with a new approach, or with a different project that is Drupal 9 compatible? Also consider new best practices. For example, Media Library can replace Entity Browser for many use cases, now that it's stable.
  • Which of these modules are the highest impact for my project? And what can I do to help move those ones closer to Drupal 9 readiness?
  • If I can't do this work myself who do I need to start working with to coordinate?

We've got a tutorial, Prepare for a Drupal-to-Drupal Migration that has lots of ideas about how to start the process of preparing for a Drupal 7 to Drupal 8 migration that's relevant here. One of the big ones is, start a spreadsheet and start collaborating with your team on tracking the status of things.

Example:

Google sheet showing a list of Drupal 7 modules and notes about their drupal 8 readiness.

Also, check out the Upgrade Rector project which aims to provide a UI for the drupal-rector toolset.

Related Topics: 

Comments

Thank you for such detailed information.It help a lot to start migration to Drupal version 9

Add new comment