Aller au contenu principal

Politique de compatibilité

À partir de la version 1.0.0, Canopy s'engage à une compatibilité ascendante documentée au sein d'une ligne de version majeure. Cette page est le contrat : elle décrit ce qui reste stable, ce qui peut changer et comment fonctionnent les cycles de dépréciation, afin que les opérateurs puissent planifier les mises à niveau sans surprises.

La politique s'applique à 1.x. Une future ligne 2.x pourra la réviser ; dans ce cas, un guide de migration sera livré avec les notes de version 2.0.0.

Ce qui est couvert​

Schéma de base de données (migrations Alembic)​

Dans 1.x :

  • Les migrations sont additives ou rétrocompatibles lors de la mise à niveau.
  • De nouvelles colonnes peuvent être ajoutées à tout moment.
  • Les colonnes existantes ne seront pas supprimées sans passer par un cycle de dépréciation.
  • Les colonnes existantes ne seront pas renommées sans un cycle de dépréciation (un renommage est implémenté comme ajouter-nouvelle-colonne → remplir → déprécier-ancienne-colonne → supprimer-dans-la-prochaine-majeure).
  • Les changements de type sont limités à l'élargissement (par ex. varchar(80) → varchar(255)) ; les changements de rétrécissement passent par la dépréciation.
  • Les contraintes de clé étrangère ne deviendront pas plus strictes (par ex. ON DELETE SET NULL devenant ON DELETE CASCADE) sans un cycle de dépréciation.

Les opérateurs peuvent effectuer des mises à niveau avec confiance ; la migration automatique au démarrage du backend est sûre à exécuter sur des données de production.

Métamodèle intégré​

Dans 1.x, le métamodèle livré dans backend/app/services/seed.py est stable :

  • Les clés de types de fiches intégrés (Application, Initiative, BusinessCapability, etc.) ne seront pas renommées ou supprimées.
  • Les clés de champs intégrés sur ces types ne seront pas supprimées sans un cycle de dépréciation.
  • Les clés de types de relations intégrées ne seront pas renommées ou supprimées sans un cycle de dépréciation.
  • Les sous-types par défaut livrés avec les types intégrés sont stables.

Les personnalisations propres aux opérateurs (types de fiches personnalisés, champs personnalisés ajoutés via l'interface d'administration, types de relations personnalisés) appartiennent à l'opérateur et ne sont pas couvertes par cette politique.

API REST (/api/v1/)​

Dans 1.x :

  • Les points de terminaison sous /api/v1/ ne seront pas supprimés sans un cycle de dépréciation.
  • Les noms de champs de requête et de réponse existants ne seront pas renommés sans un cycle de dépréciation.
  • Les types de champs ne changeront pas de manière incompatible (par ex. chaîne → tableau).
  • Les nouveaux champs de requête optionnels et les nouveaux champs de réponse ne sont pas cassants et peuvent apparaître dans n'importe quelle release mineure.
  • Les nouveaux points de terminaison ne sont pas cassants et peuvent apparaître dans n'importe quelle release mineure.
  • La sémantique d'authentification (JWT Bearer, la forme du payload /auth/login) est stable.
  • La sémantique des codes de statut HTTP est stable pour les chemins de succès et d'erreur documentés.

Le comportement au-delà de la surface documentée (en-têtes non documentés, texte de message d'erreur interne, ordre sans sort_by spécifié) n'est pas couvert.

Clés de permission​

Les clés de permission définies dans backend/app/core/permissions.py sont stables dans 1.x. De nouvelles clés peuvent être ajoutées ; les clés existantes ne seront pas renommées ou supprimées sans un cycle de dépréciation.

L'ensemble des permissions accordées par défaut aux rôles initialisés (admin, bpm_admin, member, viewer) peut changer entre les releases mineures, avec un avertissement dans le CHANGELOG. Les opérateurs qui ont personnalisé les permissions de rôle dans leur déploiement ne sont pas affectés.

Configuration (variables d'environnement)​

Les variables d'environnement existantes documentées dans CLAUDE.md et README.md sont stables dans 1.x. De nouvelles variables peuvent être ajoutées avec des valeurs par défaut raisonnables. Les valeurs par défaut peuvent changer avec un avertissement dans le CHANGELOG lorsque le changement est pertinent pour les opérateurs (par ex. un nouveau port par défaut).

Secrets chiffrés au repos​

Le marqueur de préfixe enc: et la clé dérivée de Fernet dans backend/app/core/encryption.py sont stables dans 1.x. Les opérateurs n'ont pas besoin de rechiffrer les secrets lors des mises à niveau mineures.

Cycle de dépréciation​

Lorsque quelque chose couvert par cette politique doit être supprimé :

  1. Marquer comme déprécié dans la version mineure N. L'entrée CHANGELOG inclut une section Deprecated signalant le changement. Pour les points de terminaison API, la route dépréciée émet un en-tête de réponse Deprecation: true (RFC 8594) et un en-tête Sunset indiquant la cible de suppression la plus précoce.
  2. Continuer à prendre en charge dans la version mineure N+1. La suppression ne peut pas avoir lieu dans la même version mineure que la dépréciation. La forme dépréciée continue de fonctionner.
  3. Suppression la plus précoce dans la version mineure N+2 ou dans 2.0 (la première des deux). La suppression arrive avec une section Removed dans le CHANGELOG et une note de migration.

Pour les changements de forme de données (migrations Alembic), la même cadence N → N+1 s'applique, exprimée comme ajouter-nouveau → remplir → supprimer-ancien.

Ce qui n'est pas couvert​

Ces éléments sont explicitement hors du champ d'application et peuvent changer à tout moment :

  • La structure interne des modules Python sous backend/app/. Les imports de app.models, app.services, etc. ne font pas partie de l'API publique. Les plugins ou scripts qui dépendent d'imports internes doivent épingler une version spécifique de Canopy.
  • La structure des blobs JSONB stockés dans les tables intégrées (fields_schema, section_config, attributes, lifecycle) au-delà de ce qui est lu par l'API REST documentée. La forme JSON sur disque peut évoluer pour prendre en charge de nouvelles fonctionnalités.
  • Les éléments internes du frontend : chemins de fichiers de composants, signatures de props des composants dans frontend/src/, le contenu de frontend/src/types/index.ts et le style des composants MUI. Les opérateurs utilisant le frontend intégré sont protégés ; quiconque intègre des composants depuis l'arborescence source est à ses propres risques.
  • Les personnalisations du métamodèle introduites par les opérateurs. Si vous ajoutez un type de fiche ou un champ personnalisé via l'interface d'administration, vous gérez votre propre migration.
  • Les données de démonstration et d'initialisation (SEED_DEMO=true). Le jeu de données de démonstration peut évoluer librement entre les releases.
  • Les services tiers intégrés : version de DrawIO, image Ollama intégrée, version de swagger-ui-dist intégrée. Ceux-ci peuvent être mis à niveau à tout moment.
  • Le comportement avec des configurations non par défaut explicitement signalées comme expérimentales dans les entrées CHANGELOG.

Ce que 1.0.0 change réellement​

Par rapport à la série 0.x, 1.0.0 lui-même n'est pas une release de fonctionnalités – c'est le point à partir duquel les engagements ci-dessus commencent à s'appliquer. Le code livré dans 1.0.0 est le même code que celui livré dans 0.71.0, plus le renforcement de la chaîne d'approvisionnement et les changements de flux contributeur documentés dans l'entrée CHANGELOG de 1.0.0.

Les releases antérieures à 1.0 n'étaient pas couvertes par cette politique. Les migrations entre les versions 0.x pouvaient et incluaient des suppressions de schéma, des renommages et des changements cassants du métamodèle. À partir de 1.0.0, ceux-ci passent par le cycle de dépréciation.