Quand une application commence à vivre (modules maison, scripts de migration, endpoints spécifiques, front custom), une montée de branche vers la 9 peut rapidement devenir un « petit chantier » si l’on n’anticipe pas les ruptures de compatibilité. L’objectif n’est pas seulement de passer le code, mais de sécuriser tout ce qui gravite autour : structure des modules, imports, API internes/exposées et environnement d’exécution.
Dans cet article orienté terrain, on déroule une checklist pragmatique pour sécuriser les migrations en mettant l’accent sur la vérification des modules et des API avant la montée vers la branche 9. Les points de contrôle s’appuient sur la documentation officielle Frappe (guides de migration) et sur un changement clé : l’introduction du Data Migration Tool en v9.
1) Partir de la référence officielle : les guides de migration
Avant d’ouvrir votre IDE, commencez par la source la plus fiable : les pages officielles de migration Frappe. Le wiki centralise les entrées « Migration Guide » et les pages « Migrating to Version 13/14/15/16 », ce qui confirme une pratique essentielle : une revue de compatibilité doit d’abord s’appuyer sur la documentation de la version cible (et des étapes intermédiaires si votre saut de version est important).
Pourquoi c’est déterminant ? Parce que les migrations ne se limitent pas à des « breaking changes » évidents. Les guides listent aussi des refactors, des dépréciations, des suppressions d’exports, des modifications de sous-chemins front, et des ajustements de dépendances. Autrement dit, vous y trouverez précisément les signaux faibles qui cassent des scripts de migration ou des imports.
Concrètement, créez un document d’audit (ou une issue par thème) et mappez chaque point des guides à votre code : modules impactés, endpoints custom, scripts de migration, dépendances. Cette étape vous évite la migration « à l’aveugle » et sert de base à vos tests de non-régression.
2) Inventaire des modules impactés : détecter les déplacements, extractions, suppressions
Un risque récurrent dans l’écosystème Frappe/ERPNext est l’évolution de la structure des modules : certains peuvent être déplacés, extraits ou supprimés entre versions. C’est exactement le type de rupture qui peut se manifester brutalement lors d’une montée vers une branche comme la 9, surtout si vous avez des apps personnalisées qui importent des éléments internes.
L’action la plus rentable ici est un inventaire des modules impactés : listez vos apps, leurs modules Python, leurs hooks, et tous les points d’entrée exécutés pendant une migration (patches, scripts, hooks d’install/upgrade). Ensuite, repérez les références à des chemins « internes » (imports profonds) plus fragiles que les API publiques.
Pour industrialiser la détection, mettez en place un contrôle automatisé sur vos imports (par exemple un job CI qui échoue si des imports ne se résolvent plus). Les guides de migration récents insistent justement sur les modifications de chemins d’import, d’exports de paquets et de structure de modules : c’est un signal clair qu’un test de non-régression des imports doit faire partie de la checklist avant de tenter l’upgrade.
3) Contrôle des mappings Data Migration : le point clé introduit en v9
La documentation officielle indique que Frappe Framework v9 introduit le Data Migration Tool. Cela en fait un point de contrôle prioritaire avant toute montée vers la branche 9, en particulier si vous avez des scripts maison de migration de données ou des pipelines d’import.
Le Data Migration Tool repose sur des Data Migration Plans et des Data Migration Mappings. Un détail important (et parfois sous-estimé) : chaque mapping génère un module dans le module défini par le plan. Donc, au-delà de la configuration fonctionnelle, vous devez vérifier les modules générés, leurs chemins d’exécution, et leur intégration dans votre app (naming, importabilité, droits, dépendances).
Checklist pratique : (1) recenser tous les Plans/Mappings existants, (2) valider que les modules de destination existent et sont cohérents avec votre structure actuelle, (3) simuler la génération en environnement de test pour repérer les collisions de noms ou les chemins invalides, (4) exécuter les imports et scripts de bout en bout sur une base de test. L’objectif : éviter de découvrir au moment du run que le mapping pointe vers un module déplacé ou un namespace qui a changé.
4) Validation des endpoints API custom : signatures, méthodes et compatibilité
Les montées de version s’accompagnent fréquemment de changements d’API et de refactors : la documentation de migration Frappe met en évidence ce risque et impose une discipline simple : contrôler les appels API custom dans les migrations (et pas uniquement dans l’application « runtime »).
Côté serveur, passez en revue : méthodes exposées, whitelists, signatures, payloads attendus, formats de réponse. Les scripts de migration sont particulièrement sensibles, car ils appellent parfois des méthodes internes « pratiques » mais non garanties dans le temps. La validation doit donc porter sur la disponibilité de la méthode, son import, et sa signature (paramètres, valeurs par défaut, exceptions).
Côté client, n’oubliez pas que les API exposées changent aussi : les notes de migration récentes autour des stacks UI Frappe mentionnent des suppressions d’exports, des changements de sous-chemins et des remplacements d’API. Si votre migration implique une mise à niveau front (build, composants, libs), validez les appels API côté client avant l’upgrade pour éviter des régressions silencieuses (écrans blancs, erreurs de build, endpoints non appelés).
5) Compatibilité runtime et dépendances : auditer toute la chaîne
Les guides récents de migration Frappe citent des changements de prérequis runtime et de dépendances minimales. Cela confirme une règle : l’audit préalable doit inclure l’environnement d’exécution, pas seulement le code applicatif. Un upgrade « qui compile » mais qui casse sur une version de Node/Python incompatible reste un échec en production.
Faites une revue des dépendances transverses : versions Python et Node, dépendances backend, paquets front-end, et chaîne de build. Les migrations peuvent introduire des variations d’outillage (ou des versions minimales) qui impactent directement vos pipelines CI/CD et vos environnements de staging.
Dans une logique communautaire et pragmatique, le conseil le plus sûr est de reproduire l’environnement cible en staging : même image Docker, mêmes versions runtime, même pipeline de build. Ensuite seulement, rejouez vos migrations (y compris Data Migration Plans/Mappings) et mesurez : erreurs d’import, warnings de dépréciation, échecs d’install, et comportements applicatifs inattendus.
6) Test de non-régression des imports et exécution de bout en bout
Les modifications de chemins d’import et la réorganisation de modules étant un risque documenté, un test de non-régression des imports est un filet de sécurité simple et extrêmement efficace. L’idée : échouer tôt, avant même d’entrer dans des migrations longues ou des replays de données.
Structurez vos tests en trois niveaux : (1) import statique (tous les modules principaux de vos apps et scripts), (2) exécution contrôlée (commande de migration/upgrade sur une base de test), (3) scénarios fonctionnels minimaux (auth, création d’un document, appel d’un endpoint clé, exécution d’un mapping de migration). Cette approche couvre rapidement 80% des cassures typiques.
Enfin, gardez une boucle de feedback courte : à chaque correction (import ajusté, endpoint mis à jour, mapping rectifié), relancez la suite. Cela évite l’accumulation de changements non testés et rend la montée vers la branche 9 beaucoup plus prévisible, même avec des apps personnalisées et des intégrations externes.
Sécuriser une montée vers la branche 9, c’est traiter la migration comme un audit complet : modules, imports, API, mappings de données et dépendances. Le fait que le Data Migration Tool soit introduit en v9 renforce l’importance de vérifier vos Data Migration Plans/Mappings et les modules générés avant de lancer l’upgrade en conditions réelles.
En pratique, appuyez-vous sur les titres de vérification recommandés, « Inventaire des modules impactés », « Validation des endpoints API custom », « Contrôle des mappings Data Migration », « Compatibilité runtime et dépendances », « Test de non-régression des imports », et outillez-les en CI/staging. Vous transformez ainsi une migration risquée en une procédure répétable, partageable et beaucoup plus sereine pour votre équipe, votre agence ou votre boutique.

