Mettre à niveau une dépendance en toute sécurité
Objectif : déplacer une dépendance (ou un groupe étroitement couplé) vers une version plus récente en comprenant les changements cassants à l'avance, pas après coup.
Plan
- Identifier l'état actuel. Trouvez la version installée (fichier de verrouillage, pas seulement le manifeste) et la version cible. Si l'utilisateur a dit "dernière", cherchez-la avec le gestionnaire de paquets (
npm view <pkg> version,pip index versions <pkg>,cargo search, etc.) et indiquez le numéro. - Enregistrer une référence sur un arbre de travail propre : installer, compiler, tests, lint, vérification de type. Notez les échecs préexistants pour ne pas les imputer à la mise à niveau.
- Lire les vraies notes de version. Ouvrez le journal des modifications, les notes de version ou le guide de migration pour chaque version entre l'actuelle et la cible. Extrayez : changements cassants, API supprimées ou renommées, nouvelles versions minimales du runtime, valeurs par défaut modifiées, dépréciations. Citez le lien source pour chaque élément. Si vous ne trouvez pas de notes de version, dites-le et traitez la mise à niveau comme plus risquée.
- Cartographier l'impact. Utilisez
rgpour rechercher chaque API supprimée, renommée ou modifiée dans la base de code. Listez les fichiers affectés avant d'éditer.
Exécuter
- Ne mettez à niveau que cette dépendance (et les pairs requis). N'exécutez pas une mise à jour globale.
- Mettez à jour le manifeste et le fichier de verrouillage avec le gestionnaire de paquets du projet, pas manuellement.
- Effectuez les modifications de code exigées par les notes, les plus petites d'abord. Remplacez les usages dépréciés lorsque la nouvelle forme est équivalente.
- Exécutez à nouveau installation, compilation, tests, lint et vérification de type. Comparez avec la référence.
- Pour les versions majeures, exécutez également l'application ou le chemin d'exemple principal si possible, et vérifiez la taille du bundle, les avertissements au démarrage et les avertissements de dépréciation.
- Si la mise à niveau nécessite une augmentation de la version minimale du runtime ou d'un pair, arrêtez-vous et demandez avant de la modifier.
Rapport
Mise à niveau : <pkg> <de> -> <vers>
Sources : <liens vers les journaux des modifications>
Changements cassants appliqués : <liste avec références aux fichiers>
Modifications effectuées : <résumé>
Vérification : <commandes, référence vs après>
Avertissements ou suivis : <dépréciations, éléments ignorés, risques>
Annulation : annulez les modifications dans <fichiers>, ou `git revert <commit>`
Règles
- Ne jamais mettre à niveau et refactoriser dans la même modification.
- Ne jamais ignorer un test qui échoue ou assouplir une plage de version pour masquer un problème.
- Correctifs de sécurité : dites quel avis la mise à niveau adresse uniquement si vous l'avez vu dans un avis officiel ou les notes de version.
- Si une dépendance transitive force un conflit, montrez la sortie du conflit et proposez des options plutôt que d'écraser aveuglément.