Monter de version par paliers : l'ordre qui évite les surprises

Une montée de version majeure se planifie comme une échelle, pas comme un saut. L'ordre n'est pas une préférence de prestataire : il est décrit dans le guide officiel de montée majeure, et il découle directement de la façon dont Symfony gère ses dépréciations. Le respecter transforme un chantier opaque en une suite d'étapes vérifiables.

Les quatre étapes, dans cet ordre

Pourquoi l'étape 1 n'est pas facultative

Symfony développe simultanément la dernière mineure d'une branche et la majeure suivante, avec les mêmes fonctionnalités. La seule différence entre les deux, c'est que la mineure conserve les éléments dépréciés que la majeure supprime. Ce fonctionnement est documenté dans le processus de publication, et il a une conséquence directe : la dernière mineure est un banc d'essai gratuit. Elle vous dit, ligne par ligne, ce qui disparaîtra à l'étape suivante, pendant que tout fonctionne encore.

Les avertissements de dépréciation apparaissent à deux endroits, et il faut les deux. Dans l'environnement de développement, ils remontent dans la barre d'outils de débogage à chaque page visitée. Dans les tests, ils n'apparaissent pas du tout par défaut : le guide officiel précise que PHPUnit n'affiche aucun avertissement de dépréciation tant que le pont dédié n'est pas installé. Le piège est net : une suite de tests verte laisse croire qu'il n'y a rien à corriger, alors qu'elle n'a simplement rien mesuré.

Un avertissement peut aussi venir d'une bibliothèque tierce plutôt que de votre code. La même page recommande alors la démarche la plus simple : mettre à jour la bibliothèque, ces dépréciations ayant souvent déjà été traitées en amont. Cela vaut la peine de faire ce tri tôt, car il réduit le volume de messages à examiner avant d'attaquer le vôtre.

Ce que Composer fera, et ce qu'il refusera

L'étape 2 consiste à porter les contraintes de tous les paquets `symfony/` sur la nouvelle majeure, puis à lancer `composer update "symfony/*"`. Le guide signale deux détails qui font gagner du temps. D'abord, quelques paquets préfixés `symfony/` suivent leur propre numérotation, les polyfills, les composants UX, les bundles : ceux-là n'ont pas à être alignés sur la version du framework. Ensuite, un conflit de dépendances peut exiger `--with-all-dependencies`, qui autorise Composer à faire bouger aussi les paquets dont dépendent les vôtres.

Un dernier point de la même page mérite d'être connu avant de le découvrir soi-même : après un changement de majeure, il faut vider le cache en supprimant le contenu du dossier plutôt qu'en appelant la commande prévue pour cela, parce que l'application peut ne plus être capable de démarrer en console à ce stade. Un vidage de cache qui échoue juste après une montée n'est pas un symptôme de plus, c'est une conséquence attendue.

Les recettes, l'étape qu'on saute

L'étape 3 est facile à omettre, parce que rien ne casse quand on la saute. Les recettes Flex génèrent des fichiers de configuration à l'installation d'un paquet ; ces fichiers évoluent avec les versions, mais votre copie, elle, reste figée à la date d'installation. Le guide décrit la commande `composer recipes` pour lister celles qui ont une mise à jour disponible, et `composer recipes:update` pour appliquer l'écart, disponible depuis Flex 1.18. Le mécanisme construit un correctif entre la version que vous aviez et la version courante, puis l'applique ; les conflits se résolvent comme des conflits de fusion ordinaires.

La recommandation qui va avec est aussi importante que la commande : commitez ce qui est en cours avant de lancer l'opération. Un correctif appliqué par-dessus un répertoire de travail déjà modifié produit un diff illisible, et vous perdez la seule chose que cette étape apporte, la capacité à relire ce qui a changé.

Découper en livraisons, pas en une bascule

Chaque palier doit pouvoir partir en production seul. Ce n'est pas une précaution de confort : c'est ce qui permet d'attribuer une régression à un changement précis. Une montée livrée en un seul bloc après trois mois de travail vous laisse, le jour de l'incident, avec une liste de plusieurs centaines de commits et aucun moyen de savoir lequel est en cause.

Ce découpage n'est pas propre à Symfony. Les mainteneurs de Doctrine formulent exactement la même consigne dans leur document de montée : plutôt que d'enchaîner plusieurs montées majeures, ils recommandent de monter, déployer, observer, puis passer à la suivante. Quand deux projets indépendants arrivent à la même conclusion, ce n'est probablement pas une préférence de style.

Questions fréquentes