Checklist de versionnage
Guide pratique pour évaluer les changements dans les API et les événements — comment distinguer les changements breaking des non-breaking et que vérifier avant de déployer.
Pourquoi une checklist ?
Chaque fois que vous modifiez une API ou un schéma d’événement, vous devez évaluer l’impact du changement. Cette checklist vous aide à classer les changements, identifier les risques et prendre les bonnes décisions avant que le changement n’arrive en production.
Classification des changements
Changements non-breaking (sûrs)
Ces changements sont rétrocompatibles et peuvent généralement être déployés sans coordination :
- ✅ Ajouter un nouveau champ optionnel à une réponse d’API
- ✅ Ajouter un nouvel endpoint
- ✅ Ajouter un paramètre de requête optionnel
- ✅ Ajouter un nouveau champ optionnel à un événement (avec valeur par défaut)
- ✅ Ajouter un nouveau type d’événement
- ✅ Enrichir la documentation ou les descriptions
- ✅ Améliorer les messages d’erreur sans changer les codes de statut
- ✅ Ajouter de nouveaux codes de statut pour des cas non couverts auparavant
Changements breaking (nécessitent une coordination)
Ces changements cassent les consommateurs existants et nécessitent une stratégie de migration :
- ❌ Supprimer un champ d’une réponse d’API
- ❌ Renommer un champ existant
- ❌ Changer le type d’un champ (string → number, object → array)
- ❌ Rendre obligatoire un champ qui était optionnel
- ❌ Supprimer un endpoint
- ❌ Changer l’URL d’un endpoint
- ❌ Supprimer un champ d’un événement
- ❌ Changer la sémantique d’un champ existant
- ❌ Réduire les valeurs acceptées dans un enum
- ❌ Changer les codes de statut HTTP pour des cas existants
Changements ambigus (à évaluer au cas par cas)
Ces changements peuvent être breaking ou non selon le contexte :
- ⚠️ Ajouter une nouvelle valeur à un enum — breaking si les consommateurs font un switch exhaustif
- ⚠️ Rendre un champ optionnel obligatoire dans une requête — breaking pour les consommateurs qui ne l’envoyaient pas
- ⚠️ Ajouter des validations plus strictes — breaking pour les consommateurs qui envoyaient des données auparavant acceptées
- ⚠️ Changer l’ordre des champs dans une réponse — breaking si un consommateur dépend de cet ordre
Checklist pour les changements d’API
Avant de déployer un changement dans une API, vérifiez chaque point :
1. Analyse d’impact
- Avez-vous identifié tous les consommateurs de cet endpoint ?
- Avez-vous revu les contract tests (s’ils existent) pour cet endpoint ?
- Le changement est-il rétrocompatible ?
- S’il est breaking, avez-vous défini une stratégie de migration ?
2. Versionnage
- Le changement nécessite-t-il une nouvelle version de l’API ?
- S’il est non-breaking, peut-il être inclus dans la version actuelle ?
- Avez-vous mis à jour la documentation de l’API (OpenAPI/Swagger) ?
- Avez-vous ajouté le changement au changelog ?
3. Communication
- Avez-vous informé les équipes consommatrices ?
- S’il est breaking, avez-vous défini une période de coexistence ?
- Avez-vous ajouté des headers de dépréciation si nécessaire ?
- La date de sunset est-elle communiquée et documentée ?
4. Tests
- Les contract tests passent-ils avec le changement ?
- Avez-vous vérifié que les consommateurs existants continuent de fonctionner ?
- Avez-vous ajouté des tests pour le nouveau comportement ?
- Avez-vous exécuté can-i-deploy (ou équivalent) ?
5. Déploiement
- L’ordre de déploiement est-il correct ? (généralement le producteur en premier pour les changements non-breaking)
- Avez-vous un plan de rollback en cas d’échec ?
- Avez-vous configuré un monitoring pour détecter les erreurs post-déploiement ?
Checklist pour les changements d’événements
1. Analyse de compatibilité
- Le changement est-il rétrocompatible ? (les nouveaux consommateurs lisent les anciens événements)
- Le changement est-il compatible en avant ? (les anciens consommateurs lisent les nouveaux événements)
- Les nouveaux champs ont-ils des valeurs par défaut ?
- Les consommateurs existants ignorent-ils les champs inconnus ?
2. Schema Registry
- Avez-vous enregistré le nouveau schéma dans le schema registry ?
- La validation de compatibilité a-t-elle réussi ?
- Avez-vous mis à jour la version du schéma ?
- Avez-vous documenté les changements du schéma ?
3. Upcasting (le cas échéant)
- Avez-vous besoin d’un upcaster pour les événements historiques ?
- L’upcaster est-il déterministe et sans effets de bord ?
- Avez-vous testé la chaîne complète d’upcasters ?
- Les consommateurs qui rejouent les événements historiques fonctionnent-ils correctement ?
4. Consommateurs
- Tous les consommateurs peuvent-ils gérer le nouveau format ?
- Les consommateurs ont-ils une gestion des erreurs pour les schémas inattendus ?
- L’ordre de déploiement est-il correct ? (généralement les consommateurs en premier pour les changements rétrocompatibles)
Processus recommandé pour les changements
Pour les changements non-breaking
- Implémenter le changement chez le producteur
- Mettre à jour la documentation et le changelog
- Déployer le producteur
- Informer les consommateurs des nouvelles capacités
- Les consommateurs adoptent le changement à leur rythme
Pour les changements breaking
- Communiquer le changement à l’avance
- Créer la nouvelle version (API) ou le nouveau schéma (événements)
- Mettre en place une période de coexistence
- Déployer la nouvelle version en parallèle de l’ancienne
- Coordonner la migration des consommateurs
- Surveiller l’adoption de la nouvelle version
- Déprécier l’ancienne version avec une date de sunset
- Retirer l’ancienne version lorsqu’elle n’a plus de trafic
Signaux d’alerte
Soyez attentif à ces signaux qui indiquent des problèmes dans votre processus de versionnage :
- 🚩 Vous ne savez pas combien de consommateurs a votre API
- 🚩 Vous n’avez pas de contract tests
- 🚩 Les changements breaking sont découverts en production
- 🚩 Il n’y a ni changelog ni documentation des versions
- 🚩 Les équipes ont peur de modifier les API par crainte de casser quelque chose
- 🚩 Plusieurs versions actives coexistent sans date de sunset
- 🚩 Les événements n’ont pas de champ de version dans leur schéma