Migration Odoo : guide technique pour passer de la v16/v17/v18 à v19/v20

Migrer Odoo sans perdre de données ni casser les modules custom. Checklist technique complète : XML IDs, modules _inherit, API JSON-2, Owl 3, environnement staging, et planning en 6 étapes.

Odoo sort une version majeure par an. La migration est inévitable — la question est si elle prendra 3 semaines ou 6 mois. La différence se joue quasi exclusivement sur la qualité de la base de code custom et la préparation en amont. Voici le guide technique complet que nous appliquons sur nos projets de migration.

Phase 1 : Audit de la base actuelle (avant tout)

Avant de parler de migration, auditer l'existant. Les 4 problèmes qui multiplient le coût de migration :

✓Modifications directes des fichiers core Odoo → à refactoriser en modules _inherit AVANT la migration
✓Références par integer ID dans les données XML/Python → à convertir en XML IDs (module.record_id)
✓Dépendances à des méthodes non-documentées (prefixées _ ou non listées dans la doc officielle) → à identifier et remplacer
✓XML-RPC dans les intégrations tierces → à migrer vers la JSON-2 API (deprecation en v20, suppression en v22)

Phase 2 : Environnement de staging dédié

La règle absolue : ne jamais tester une migration en production. Créer un environnement staging identique :

✓Dump de production restauré sur staging (données réelles, pas de données de test)
✓Tous les modules custom en même version que production
✓Même version PostgreSQL (Odoo 20 requiert PostgreSQL 16 minimum)
✓Même version Python (Odoo 20 requiert Python 3.12 minimum)
✓Variables d'environnement isolées (pas de connexion aux systèmes de production)

Phase 3 : Migration des modules custom

Pour chaque module custom, la procédure :

✓Vérifier les compatibilités dans manifest.py : 'version' et 'odoo_version_info' à mettre à jour
✓Pour Odoo 20 : migrer les composants frontend Owl 2 → Owl 3 (hooks et cycle de vie changent)
✓Tester chaque vue XML contre le nouveau framework — les namespaces peuvent changer
✓Vérifier les héritages de modèles : si Odoo renomme ou supprime un champ hérité, le module casse
✓Exécuter les scripts de migration dans le dossier migrations/[version]/pre-migrate.py et post-migrate.py
✓Pour les données : écrire des scripts Python qui transforment les enregistrements de l'ancien modèle vers le nouveau

Phase 4 : Migration de l'API (XML-RPC → JSON-2)

Si des systèmes externes (ERP, e-commerce, BI, scripts d'import) utilisent l'API XML-RPC d'Odoo, la migration est urgente :

✓XML-RPC : /xmlrpc/2/common et /xmlrpc/2/object → mode legacy depuis v20, suppression en v22
✓JSON-2 : nouveau endpoint standardisé avec authentification par API keys et scopes
✓Audit : grep -r 'xmlrpc' dans tout le code source des intégrations
✓Migration par intégration : une à une, tester sur staging avant de changer la production
✓Les API keys JSON-2 : créer dans Odoo → Paramètres → API Keys, configurer les scopes (read/write par module)

Phase 5 : Tests de recette réalistes

Ne pas tester avec des données fictives ('Test Client 1'). Créer des scénarios avec vos vrais clients, vrais produits, vrais workflows. Tester spécifiquement :

✓Flux de vente complet : devis → commande → livraison → facture → paiement
✓Réconciliation comptable avec les relevés bancaires réels
✓Tous les rapports PDF custom
✓Les intégrations critiques (paiements, logistique, e-commerce)
✓Les droits d'accès : tester chaque profil utilisateur
✓Les automatisations : déclencher chaque Automated Action manuellement

Phase 6 : Go-live et période de stabilisation

✓Formation des utilisateurs : 1-2 semaines avant le go-live, pas le jour J
✓Former par rôle : les commerciaux apprennent Sales, les comptables apprennent Accounting
✓Garder l'ancien système en parallèle pendant 1-2 mois (comparer les outputs)
✓Premier patch stable Odoo : attendre 4-6 semaines post-GA avant de migrer la production
✓Support renforcé les 2 premières semaines post go-live
✓Pour Odoo 20 spécifiquement : GA mi-octobre 2026, premier patch stable novembre 2026

Une migration bien préparée prend 2-4 semaines. Une migration dans une base surchargée de code custom non documenté peut prendre 6 mois. Investir dans la qualité du code maintenant est toujours moins cher que de le payer lors de la prochaine migration.