Before upgrading this site to Drupal 11, I worked through the smaller upgrades first, and one of them was Drush, from 12.5.3 to 13.7.6. A major version of the tool you run every database update and config import through deserves a careful look. Here's what I checked, why the target was 13.7 rather than just 13, and what the most-cited breaking change in Drush 13 turned out to mean in practice.
Why 13.7, not just 13
The site's composer constraints would have accepted any Drush 13. I targeted 13.7 specifically, because that's what drupal/devel 5.5.0 requires. That way the Drush upgrade also unblocked a later devel update, without doing that update in the same step.
The breaking change that matters: how commands are registered
Drush's documentation for creating custom commands says it directly: Drush 13 and later expect command files to use the AutowireTrait to get their dependencies, and the older way, a drush.services.yml file in the module, is deprecated. Its page on dependency injection dates the deprecation earlier, to Drush 12. Command files are also expected under the module's src/Drush/ directory since Drush 12.
So the question before upgrading was: what on this site defines Drush commands the old way?
- The site's own code: nothing. There are no custom Drush commands in the custom modules or theme, so nothing of ours could break.
- Contrib modules: several do. Installed modules that still ship a
drush.services.ymlinclude encrypt, key, scheduler, ultimate_cron and xmlsitemap.
The commit that did the upgrade was cautious about those: their commands might stop registering. That was acceptable, because nothing in this site's workflow uses them. The commands it does use are all core Drush: config:*, cache:rebuild, updb, role:*, user:*, pm:*, sql:* and php:eval.
What actually happened to the contrib commands
For this article I checked, on the local copy of the site running the same Drush 13.7.6. The commands from the modules that still use drush.services.yml are all there in drush list: encrypt:encrypt and its siblings, key:list, scheduler:cron, the cron:* commands from ultimate_cron, and xmlsitemap:rebuild and xmlsitemap:regenerate.
So in 13.7, "deprecated" means exactly that: still working, scheduled to go. The cautious reading in the commit was the right one to plan with, because a deprecated mechanism can be removed in a later release, but it hadn't happened yet. When it does, the fix belongs in each module, not on the site: the commands have to move to an autowired command class.
Testing it
The test after upgrading was to run every core command the site's own workflow had used that day and compare: config:status, cache:rebuild, updb, role:list, user:information and sql:query all behaved as before, the site was healthy, and the publishing pipeline that posts articles through JSON:API still worked. That's a small test, but it's the right one: it covers what the site actually depends on, rather than everything Drush can do.
If a command goes missing after upgrading
If a command you rely on disappears from drush list after a Drush upgrade, check how the module that provides it registers commands before anything else. A module with a drush.services.yml and no classes under src/Drush/Commands is using the deprecated mechanism, and the module's issue queue is the place to look for, or ask for, a port. Running ls modules/contrib/*/drush.services.yml before you upgrade tells you in a second which modules that applies to.
The Drupal 11 upgrade that followed, and the outage it led to, is a separate story.
Leave a comment
Comments are reviewed before they appear.