Upgrade Status : lire le rapport et trier ce qui bloque la mise à jour vers Drupal 11

Un rapport Upgrade Status ne se lit pas comme une liste d'erreurs à compter. Il se lit en trois passages : l'environnement (PHP, base de données, version du cœur), puis les groupes de projets, qui disent quoi faire de chaque module, et enfin le détail du code sur mesure, ligne par ligne. Dans ce détail, un seul critère sépare ce qui bloque Drupal 11 de ce qui peut attendre : la version à laquelle l'API dépréciée est retirée. À un peu plus de deux mois de la fin de vie de Drupal 10, le 9 décembre 2026, c'est ce tri qui permet de savoir où porter l'effort.

Cet article porte sur la lecture du rapport. Le traitement des modules contrib eux-mêmes (patch, plugin lenient, remplacement) est détaillé dans l'article sur les modules incompatibles avec Drupal 11.

Avant de lire : obtenir un rapport fiable

Upgrade Status analyse le site sur lequel il est installé et évalue sa préparation à la version majeure suivante. Pour préparer Drupal 11, il s'exécute donc sur le site Drupal 10, de préférence sur une copie de préproduction.

Deux points à vérifier avant de se fier au résultat :

• La branche du module. La version stable 4.x fonctionne avec Drupal 9, 10 et 11. La branche 5.0, encore en alpha, demande Drupal 10.4 au minimum et vise aussi Drupal 12. Pour un passage de 10 à 11, la 4.x suffit.
• L'installation par Composer. La page du projet indique que le module doit être installé avec Composer, à cause de ses dépendances PHP (PHPStan notamment). En cas de conflit avec Drush, elle décrit une procédure qui passe par drupal/core-dev.

L'analyse peut se lancer depuis l'interface (Rapports > Upgrade Status) ou avec Drush, plus pratique sur un site qui compte beaucoup de modules :

# Tous les projets du site
drush upgrade_status:analyze --all

# Uniquement le code sur mesure, sans les modules non installés
drush us-a --all --ignore-contrib --ignore-uninstalled

# Si PHPStan manque de mémoire sur un gros projet
drush us-a mon_module --phpstan-memory-limit=2G

Les options --ignore-contrib, --ignore-custom, --ignore-uninstalled, --ignore-list et --skip-existing sont documentées sur la page du projet. Elles servent surtout à découper l'analyse pour relire un périmètre à la fois.

Premier passage : le bloc environnement

Commencez toujours par là. Un blocage d'environnement ne dépend pas de votre code, souvent pas de vous non plus : il faut une intervention de l'hébergeur, et c'est ce qui se planifie le plus tôt.

Le rapport vérifie notamment la version de Drupal, de PHP, de la base de données et de Drush, ainsi que la présence de modules du cœur dépréciés. Les valeurs attendues pour Drupal 11, d'après la documentation de drupal.org :

Si PHP ou la base de données sont sous ces seuils, le reste du rapport peut être parfait : la mise à jour ne passera pas. Pour la version de PHP, l'article sur la fin de support de PHP 8.2 détaille ce qu'il faut demander à l'hébergeur.

Le même bloc signale les modules du cœur retirés dans Drupal 11 : Actions UI, Activity Tracker, Book, Forum, Statistics et Tour. S'ils sont installés, il faut soit les désinstaller, soit ajouter leur version contrib avant de passer le cœur en 11.

Deuxième passage : les groupes de projets

Le rapport ne classe pas les modules par nombre de problèmes, mais par action suggérée. Ce choix, expliqué par l'auteur du module, Gábor Hojtsy, change la façon de lire : chaque groupe est une file de travail.

Pour chaque projet contrib, le rapport distingue deux informations : la compatibilité de la version installée (ce que dit le code sur le disque) et celle de la version disponible sur drupal.org. Un module incompatible en local mais compatible sur drupal.org relève d'une simple mise à jour. Un module incompatible des deux côtés est un vrai point bloquant.

Pour le groupe Collaborate with maintainers, un réflexe utile : ouvrir la file d'issues du module et chercher un ticket intitulé « Automated Drupal 11 compatibility fixes ». Il est ouvert par le Project Update Bot, qui combine justement Upgrade Status et Drupal Rector pour proposer des correctifs aux projets contrib. Ce ticket est un point de départ, pas une garantie : vérifiez qu'il a été relu et testé.

Un mot sur Remove : un module non installé ne gêne pas Drupal, mais son paquet reste dans composer.json. S'il déclare une contrainte drupal/core limitée à Drupal 10, il empêchera Composer d'installer Drupal 11. Le retirer est la correction la moins chère du rapport.

Troisième passage : le détail d'un projet

C'est là que les rapports impressionnent : un module sur mesure peut afficher des dizaines de lignes. Chaque ligne indique un fichier, un numéro de ligne et un message. Pour les API PHP de Drupal, ce message suit un format imposé par la politique de dépréciation de Drupal :

%élément% is deprecated in drupal:X.Y.Z and is removed from drupal:A.B.C.
%consigne de remplacement%. See https://www.drupal.org/node/…

Deux informations de ce message font tout le tri :

• La version de retrait (is removed from). Si elle vaut drupal:11.0.0, l'API n'existe plus dans Drupal 11 : c'est bloquant. Si elle vaut drupal:12.0.0, l'API fonctionne encore en Drupal 11 : la correction peut être planifiée plus tard, avant le passage à Drupal 12.
• Le lien final, vers la fiche de changement (change record) sur drupal.org. C'est là que se trouve la manière de corriger, souvent avec un exemple avant/après.

Le rapport ajoute à chaque problème une étiquette de tri. L'auteur du module décrit les principales : Fix now pour ce qui peut et doit être corrigé maintenant, Fix later pour ce qui peut attendre, Check manually quand l'outil ne peut pas trancher avec les informations dont il dispose. Les problèmes que Drupal Rector sait corriger sont signalés comme tels.

Au-delà du PHP, la documentation drupal.org sur les outils de détection liste d'autres types de constats :

• une syntaxe Twig dépréciée dans les templates du thème ou des modules ;
• l'utilisation ou l'extension de bibliothèques dépréciées (déclarations libraries.yml) ;
• une clé core_version_requirement absente ou insuffisante dans le fichier .info.yml.

Ce dernier constat est le plus simple à corriger, et il est bloquant : sans ^11 dans cette clé, Drupal refusera d'activer le module, même si son code est parfait.

Le tableau de triage

Une fois les trois passages faits, chaque constat entre dans l'une de ces lignes :

Pour les lignes « Drupal Rector », la marche habituelle est de lancer l'outil en simulation avant d'écrire quoi que ce soit :

composer require --dev palantirnet/drupal-rector
cp vendor/palantirnet/drupal-rector/rector.php .
vendor/bin/rector process web/modules/custom/mon_module --dry-run

D'après sa documentation, les règles couvrent les dépréciations de Drupal 10.0 à 11.4, et l'outil peut être exécuté sur un site encore en Drupal 10. Relancez ensuite Upgrade Status sur le module : les lignes restantes sont celles à corriger à la main.

Ce que le rapport ne voit pas

Upgrade Status s'appuie sur une analyse statique : il lit le code sans l'exécuter. Un rapport vide sur un projet signifie qu'aucun usage détectable d'API dépréciée n'a été trouvé, pas que le module fonctionnera à l'identique en Drupal 11.

Restent donc à vérifier par d'autres moyens :

• les changements de comportement qui ne passent pas par une API dépréciée ;
• ce qui se construit à l'exécution (nom de classe ou de service calculé, par exemple), que l'analyse ne peut pas suivre ;
• la configuration du site et les données, que l'outil n'analyse pas.

C'est pourquoi le rapport à vert n'est qu'une étape. La recette sur une préproduction en Drupal 11 reste indispensable.

Suivre l'avancement

Le rapport est utile une fois, il l'est davantage relancé à chaque étape. Drush sait produire un résultat exploitable par une chaîne d'intégration continue :

drush us-a --all --ignore-contrib --format=codeclimate > upgrade-status.json

Les formats plain, checkstyle (XML) et codeclimate (JSON) sont disponibles. La page du projet précise que le format Code Climate s'intègre à GitLab CI pour afficher les constats dans les demandes de fusion. Suivre le nombre de constats bloquants d'une exécution à l'autre donne une mesure plus honnête de l'avancement qu'une impression générale.

Par où commencer

Si vous n'avez pas encore installé Upgrade Status, deux outils gratuits donnent un premier aperçu sans rien toucher au site : le vérificateur de version Drupal, pour connaître la version et sa date de fin de support, et le vérificateur de modules Drupal 11, qui indique pour chaque module contrib s'il existe une version compatible. Ils ne remplacent pas Upgrade Status : ni l'un ni l'autre ne lit votre code sur mesure.

Si votre rapport ne montre que des mises à jour contrib et quelques lignes corrigeables par Rector, une équipe à l'aise avec Composer et Drush peut mener la mise à jour elle-même, en suivant le déroulé de la page mise à jour Drupal 10 vers 11. Si l'environnement bloque, si plusieurs modules sont dans Collaborate with maintainers ou si le code sur mesure accumule les Check manually, c'est là qu'un audit est utile : l'audit flash reprend ce rapport, tranche chaque ligne et débouche sur un devis ferme, avec une date de bascule compatible avec le 9 décembre.

Sources, consultées en septembre 2026 : drupal.org, Upgrade Status ; drupal.org, How to upgrade from Drupal 10 to Drupal 11 ; drupal.org, PHP requirements et Database server requirements ; drupal.org, Deprecation checking and correction tools ; drupal.org, Drupal deprecation policy ; drupal.org, Project Update Bot ; drupal.org, Drupal core release schedule ; Drush, Install ; Palantir, Drupal Rector ; Gábor Hojtsy, Evolving the Upgrade Status user interface et First beta of Upgrade Status for Drupal 8.