Politique pour la 1.0 et les versions suivantes : les contrats publics documentés constituent la référence. Les versions mineures et correctives la préservent ; les ruptures planifiées nécessitent une version majeure et une annonce préalable.
Quels changements examiner ?
Examiner la configuration documentée, les scénarios, les sélecteurs, les sorties et codes de retour des commandes, les champs et erreurs HTTP, les métriques, les schémas du journal et les environnements pris en charge. Les valeurs par défaut, l’ordre des actions, l’authentification, les unités, les libellés et les motifs destinés aux traitements automatisés en font partie. Version de l’application, version des routes HTTP et schéma des données persistantes sont des identifiants distincts.
Même un champ facultatif peut perturber un consommateur strict : considérer les valeurs énumérées, les colonnes CSV fixes et la cardinalité des métriques. Les classes Python internes, les messages de diagnostic, les abréviations implicites des options et les comportements non documentés ne sont pas des interfaces stables ; leurs conséquences opérationnelles connues doivent néanmoins être expliquées. Les motifs destinés aux traitements automatisés restent en anglais et se distinguent des messages de diagnostic.
Annoncer avant de supprimer
- Décrire dans la proposition de modification le comportement actuel, les utilisateurs concernés, la solution de remplacement et les risques, avec un lien vers le contrat concerné.
- Publier la solution de remplacement et l’annonce dans au moins une version publiée, en conservant l’ancien comportement documenté utilisable. Une annonce sur la seule branche de développement ne suffit pas.
- Nommer la version d’annonce et la première version pouvant supprimer l’ancien comportement. La suppression doit intervenir dans une version ultérieure. Sans échéance définie, le préciser puis annoncer la version visée avant suppression. Aucun délai calendaire ni retrait automatique n’est fixé.
- Avant suppression, vérifier la migration entre les versions de départ et d’arrivée indiquées, actualiser les guides et exemples, puis publier les limites du retour arrière et les résultats des essais pour examen par le mainteneur.
Les annonces figurent dans le guide concerné et les notes de version publiées, accessibles depuis la proposition de modification de la version. Des avertissements à l’exécution peuvent les compléter sans altérer les sorties structurées. Aucun mécanisme d’avertissement n’est ajouté ici. Fixer les versions déployées et lire les annonces intermédiaires lors d’un saut de versions ; la maintenance et le report des correctifs sur toutes les anciennes 0.0.x ne sont pas garantis indéfiniment.
Exceptions urgentes
Une faille de sécurité confirmée ou un risque de perte de données peut justifier une correction incompatible immédiate. Le mainteneur doit expliquer dans la version corrigée pourquoi attendre serait dangereux, les versions touchées, les conséquences opérationnelles, le remplacement ou la récupération et les restrictions de retour arrière. La confidentialité des détails d’exploitation ne doit pas masquer les conséquences opérationnelles. La commodité, le nettoyage du code ou la simple étiquette « correction de bogue » ne dispensent pas d’annonce préalable.
Migration et retour arrière
Les modifications de configuration et de commandes nécessitent des exemples avant/après, des étapes de validation, les nouvelles valeurs par défaut et les conséquences sur la sélection des actions. Ne pas réinterpréter silencieusement les règles existantes. Les choix de sélection et comparaison ont été introduits en 0.0.80 et sont conservés en 1.0.
Pour HTTP et les métriques, identifier les consommateurs et expliquer la coexistence ou la gestion des versions. Le préfixe /v1 n’autorise pas un changement silencieux de sens ; les critères imposant une nouvelle version de route restent à décider séparément.
Avant d’activer une écriture incompatible, publier un tableau de lecture/écriture associant versions exactes de l’application et schémas, des essais d’historiques mélangés, les consignes de sauvegarde et les limites du retour arrière. Préférer une adaptation sans perte à la lecture. Une conversion physique nécessaire doit être explicite, préserver les octets d’origine, écrire séparément, proposer une simulation, vérifier nombres et identifiants, et expliquer la récupération après interruption. Un format inconnu doit provoquer une erreur explicite.
La commande facultative audit-migrate convertit les schémas 1/2 du journal vers le schéma 2 ; elle ne migre ni la configuration ni l’état des actions et ne remplace pas le journal actif. Elle ne certifie pas toutes les mises à niveau ou tous les retours à une ancienne version.
Identifier tous les chemins persistants et les processus d’écriture, arrêter ces derniers pour une sauvegarde cohérente, conserver les droits et tester sur des copies. Vérifier collecte, état, historique et exports avant reprise. Avant retour arrière, conserver séparément les données ajoutées depuis la mise à niveau et vérifier l’ancienne lecture et configuration sur des copies. Une sauvegarde restaurée peut exclure les événements récents : documenter toute limite de conservation et la procédure de récupération. Ne jamais rejouer les actions parce que les événements ont été migrés. Un essai de copie sur la même version ne valide pas une mise à niveau entre versions.
Contenu obligatoire d’une annonce
À la publication, préciser les versions exactes ; cette liste est un modèle, pas une suppression programmée. Expliquer tout champ sans objet. Les annonces de référence et les exemples destinés aux traitements automatisés restent en anglais.
- Interface concernée, ancien comportement et motif du changement.
- Version d’annonce et de remplacement ; première version de suppression possible, ou absence d’échéance.
- Versions de départ et d’arrivée concernées et réellement testées.
- Solution de remplacement et exemple avant/après.
- Commandes de validation et de migration.
- Données persistantes, sauvegarde et récupération après interruption.
- Limites du retour arrière et traitement des données ajoutées depuis la mise à niveau.
- Résultats des essais de régression et de mise à niveau, limites connues.
- Ticket ou proposition de modification associé ; justification d’une exception urgente, le cas échéant.
La politique sur GitHub est la référence maintenue. La feuille de route sépare les validations acquises des observations prolongées encore ouvertes.