Conduire une migration avec un agent
Découper une version majeure en lots réversibles, avec des points de contrôle qui ne se limitent pas à « ça compile ».
« Migre le projet vers la version 3 » lancé dans une conversation donne, une heure plus tard, un diff de quatre cents fichiers. Le projet ne démarre plus, trente tests sont rouges, et tu ne sais plus lesquelles de ces modifications étaient nécessaires. La seule option raisonnable est de tout jeter.
Ce n'est pas un problème de modèle, c'est un problème de découpage. Une migration réussie n'est jamais un grand changement : c'est une série de petits changements dont chacun laisse le projet dans un état qui fonctionne. Ce qui distingue les deux, ce n'est pas la quantité de code touché, c'est le nombre de points où tu peux t'arrêter sans dégât.
Un agent accélère beaucoup l'exécution de chaque lot. Il ne décide pas du découpage à ta place, et c'est le découpage qui détermine si la migration aboutit ou si elle finit abandonnée sur une branche.
Avant de commencer
- Un dépôt git propre, sans modification en cours
- Une suite de tests, ou au minimum un scénario manuel que tu sais rejouer
- Les notes de version de la cible, ouvertes à côté
1Fixer l'état de départ
Avant toute modification, tu as besoin d'un point de retour nommé, et de la preuve que le projet fonctionnait avant.
git switch -c migration-v3
git tag avant-migration-v3
Note aussi ce qui marche, parce que la mémoire est mauvaise juge après trois jours de migration :
Avant qu'on touche a quoi que ce soit : lance la suite de tests et le
demarrage de l'application. Ecris dans un fichier MIGRATION.md le nombre
de tests qui passent, ceux qui echouent deja, et les avertissements au
demarrage.
C'est notre reference. Ne corrige rien maintenant.
Les tests déjà rouges avant la migration sont ceux qui empoisonnent le diagnostic ensuite. Les avoir écrits noir sur blanc évite trois heures de recherche sur une régression qui n'en est pas une.
2Inventorier avant d'écrire une ligne
La question n'est pas « comment migrer » mais « qu'est-ce qui casse ». Elle se répond en lecture, pas en édition.
npm outdated
npx npm-check-updates --target minor
npm-check-updates s'installe et s'invoque en version longue avec npx ; son
binaire s'appelle ncu une fois installé. --target minor limite aux versions
mineures et correctives, -u réécrit le package.json. Garde -u pour plus
tard : à ce stade, tu regardes.
Ensuite, la lecture que l'outil ne fait pas :
Voici les notes de version entre notre version et la cible. Croise-les
avec notre code et rends un tableau : rupture annoncee, fichiers de chez
nous concernes, nombre d'occurrences, effort estime.
N'inclus pas les ruptures qui ne nous concernent pas. Si tu n'es pas sur
qu'une rupture nous touche, mets "a verifier" au lieu de trancher.
Ce tableau est le vrai plan de migration. Il transforme une tâche floue en une liste finie, et il te dit tout de suite si la migration tient en un après-midi ou en deux semaines.
3Migrer par lots qui compilent
Un lot, c'est un groupe de ruptures liées, une branche, un commit, et un projet qui fonctionne à la fin. L'ordre habituel : d'abord ce qui est mécanique et massif, ensuite ce qui demande une décision.
On traite uniquement la ligne 1 du tableau : [RUPTURE].
Contraintes :
- ne touche aucun autre sujet, meme si tu vois un probleme a cote ;
- ne modifie aucun test ;
- a la fin, lance la suite et montre-moi le resultat compare a
MIGRATION.md.
Si le lot depasse une vingtaine de fichiers, arrete-toi et propose un
decoupage plus fin avant de continuer.
Beaucoup d'écosystèmes publient des transformations automatiques pour les
ruptures mécaniques : jscodeshift côté JavaScript, pyupgrade et
django-upgrade côté Python, et les règles de correction automatique de ruff.
Quand un codemod officiel existe pour ta cible, il est plus fiable qu'une
réécriture à la main ou par un agent, et surtout il est rejouable.
Vérifie ce qui existe pour ta version précise
Les outils de migration automatique changent de nom et de portée d'une version majeure à l'autre. Avant de lancer une commande trouvée dans un article, va lire la page de migration de la version exacte que tu vises. Une transformation prévue pour la version 2 peut faire des dégâts silencieux sur la version 3.
4Un point de contrôle qui ne soit pas « ça compile »
« Ça compile » est le contrôle le plus faible qui existe. Il laisse passer les comportements changés, qui sont justement ce qu'une version majeure modifie.
Définis pour chaque lot un contrôle observable, et exige la sortie :
- la suite de tests, comparée à la référence de l'étape 1 ;
- le démarrage de l'application, sans nouvel avertissement ;
- un ou deux parcours réels, exécutés et décrits.
Ne me dis pas que ca marche. Montre-moi : la commande lancee, sa sortie
brute, et la difference avec les chiffres de MIGRATION.md.
Si un test qui passait avant echoue maintenant, ne le corrige pas :
signale-le et attends.
Le test ajusté pour passer
Le réflexe le plus coûteux d'une migration assistée est de modifier un test qui échoue pour l'aligner sur le nouveau comportement. Parfois c'est correct, souvent c'est la régression qu'on cherchait à éviter, désormais validée par la suite. Un test touché pendant une migration mérite un commit séparé et une justification écrite.
5Savoir revenir en arrière
Le chemin de retour se prépare avant d'en avoir besoin, et il dépend du moment où le problème apparaît.
Pendant la migration, un lot raté se jette, il ne se répare pas :
git restore .
git switch -c migration-v3-lot2 avant-migration-v3
Après fusion, on annule proprement plutôt que de réécrire l'historique :
git revert <commit>
Et quand la régression se manifeste des jours plus tard, sans qu'on sache quel lot l'a introduite, la recherche est automatisable :
git bisect start
git bisect bad
git bisect good avant-migration-v3
git bisect run npm test
git bisect run rejoue la commande sur chaque commit intermédiaire et s'arrête
sur le premier qui échoue. Cela ne fonctionne que si chaque lot laissait le
projet dans un état exécutable, ce qui est la raison d'être du découpage de
l'étape 3.
Ce qui fait échouer une migration
Les migrations abandonnées se ressemblent, et le motif technique est rarement en cause.
La branche qui vit trop longtemps. Une migration menée sur une branche isolée pendant six semaines accumule des conflits avec le travail courant, et finit par coûter plus cher à fusionner qu'à refaire. Fusionne lot par lot, même si la migration n'est pas terminée : un projet à moitié migré mais cohérent est un état viable, une branche de six semaines ne l'est pas.
Le lot fourre-tout. Un lot qui corrige la rupture prévue, plus deux détails vus au passage, plus un renommage, ne peut plus être annulé sans perdre autre chose. La contrainte « ne touche aucun autre sujet » n'est pas de la rigidité, c'est ce qui rend le retour arrière possible.
L'absence de décision sur ce qu'on ne migre pas. Une version majeure retire des fonctionnalités, et certaines n'ont pas d'équivalent. Ces cas se tranchent au début, pas quand le code ne compile plus : on remplace, on réécrit, ou on abandonne la fonctionnalité. Laisser un agent choisir à ta place donne en général une réimplémentation maison de ce que la bibliothèque faisait, écrite en vingt minutes et maintenue pour des années.
Quelques prompts pour aller plus loin
| Objectif | Prompt à adapter |
|---|---|
| Estimer avant de s'engager | Voici les notes de version et notre code. Donne-moi le nombre de fichiers touches par rupture, et dis quelles ruptures n'ont pas de solution mecanique. |
| Choisir l'ordre des lots | Propose un ordre de traitement de ces ruptures qui minimise les conflits entre lots. Justifie chaque dependance. |
| Remplacer une bibliothèque | Liste tous les points d'appel de [BIBLIOTHEQUE] dans le depot, groupes par fonctionnalite utilisee. Dis lesquelles n'ont pas d'equivalent dans [CIBLE]. |
| Isoler une dépendance | Propose une couche d'adaptation autour de [BIBLIOTHEQUE] pour que le reste du code n'en depende plus directement. Montre le diff sur un seul appelant. |
| Documenter la migration | A partir des commits de cette branche, ecris le journal de migration : ce qui a change, ce qui a ete reporte, ce qui reste a verifier en production. |
Tu as d’autres ressources comme ça ?
Ce que tu viens de lire est entièrement gratuit. Une nouvelle ressource part chaque semaine dans la newsletter : guides, modèles à copier et liens triés, sans compte à créer.
Me contacter
Une question, un projet, une envie de collaborer ? Écris-moi.
Cette page est en accès libre, n’hésite pas à la partager.