Zum Hauptinhalt springen

Kompatibilitätsrichtlinie

Ab Version 1.0.0 verpflichtet sich Canopy zu einer dokumentierten Abwärtskompatibilität innerhalb einer Major-Versionslinie. Diese Seite ist der Vertrag: Sie beschreibt, was stabil bleibt, was sich ändern kann und wie Veraltungsprozesse funktionieren, damit Betreiber Upgrades ohne Überraschungen planen können.

Die Richtlinie gilt für 1.x. Eine zukünftige 2.x-Linie kann sie überarbeiten; in diesem Fall wird ein Migrationsleitfaden mit den 2.0.0-Versionshinweisen ausgeliefert.

Was abgedeckt ist​

Datenbankschema (Alembic-Migrationen)​

Innerhalb von 1.x:

  • Migrationen sind additiv oder aufwärtskompatibel beim Upgrade.
  • Neue Spalten können jederzeit hinzugefügt werden.
  • Bestehende Spalten werden nicht ohne einen Veraltungszyklus entfernt.
  • Bestehende Spalten werden nicht ohne einen Veraltungszyklus umbenannt (eine Umbenennung wird als neue-Spalte-hinzufügen → befüllen → alte-Spalte-veraltung → in-nächster-Major-Version-entfernen implementiert).
  • Typänderungen sind auf Erweiterungen beschränkt (z. B. varchar(80) → varchar(255)); einengende Änderungen durchlaufen die Veraltung.
  • Fremdschlüsseleinschränkungen werden ohne einen Veraltungszyklus nicht strenger (z. B. ON DELETE SET NULL wird zu ON DELETE CASCADE).

Betreiber können mit Zuversicht vorwärts migrieren; die automatische Migration beim Backend-Start ist sicher auf Produktionsdaten anwendbar.

Integriertes Metamodell​

Innerhalb von 1.x ist das Metamodell, das in backend/app/services/seed.py ausgeliefert wird, stabil:

  • Integrierte Kartentyp-Schlüssel (Application, Initiative, BusinessCapability usw.) werden nicht umbenannt oder entfernt.
  • Integrierte Feldschlüssel dieser Typen werden nicht ohne einen Veraltungszyklus entfernt.
  • Integrierte Relationstyp-Schlüssel werden nicht ohne einen Veraltungszyklus umbenannt oder entfernt.
  • Standard-Subtypen, die mit integrierten Typen ausgeliefert werden, sind stabil.

Die eigenen Anpassungen von Betreibern (benutzerdefinierte Kartentypen, benutzerdefinierte Felder, die über die Admin-Benutzeroberfläche hinzugefügt wurden, benutzerdefinierte Relationstypen) liegen in der Verantwortung des Betreibers und sind von dieser Richtlinie nicht abgedeckt.

REST-API (/api/v1/)​

Innerhalb von 1.x:

  • Endpunkte unter /api/v1/ werden nicht ohne einen Veraltungszyklus entfernt.
  • Bestehende Anfrage- und Antwortfeldnamen werden nicht ohne einen Veraltungszyklus umbenannt.
  • Feldtypen werden nicht inkompatibel geändert (z. B. String → Array).
  • Neue optionale Anforderungsfelder und neue Antwortfelder sind nicht brechend und können in jedem Minor erscheinen.
  • Neue Endpunkte sind nicht brechend und können in jedem Minor erscheinen.
  • Authentifizierungssemantik (Bearer-JWT, die /auth/login-Payload-Form) ist stabil.
  • HTTP-Statuscode-Semantik ist für dokumentierte Erfolgs- und Fehlerpfade stabil.

Verhalten jenseits der dokumentierten Oberfläche (undokumentierte Header, interner Fehler-Nachrichtentext, Reihenfolge ohne angegebenes sort_by) ist nicht abgedeckt.

Berechtigungsschlüssel​

Berechtigungsschlüssel, die in backend/app/core/permissions.py definiert sind, sind innerhalb von 1.x stabil. Neue Schlüssel können hinzugefügt werden; bestehende Schlüssel werden nicht ohne einen Veraltungszyklus umbenannt oder entfernt.

Die Menge der Berechtigungen, die standardmäßig den geseedeten Rollen (admin, bpm_admin, member, viewer) gewährt werden, kann sich zwischen Minor-Releases ändern, mit einem CHANGELOG-Hinweis. Betreiber, die Rollen-Berechtigungen in ihrer Bereitstellung angepasst haben, sind nicht betroffen.

Konfiguration (Umgebungsvariablen)​

Bestehende Umgebungsvariablen, die in CLAUDE.md und README.md dokumentiert sind, sind innerhalb von 1.x stabil. Neue Variablen können mit sinnvollen Standardwerten hinzugefügt werden. Standardwerte können mit einem CHANGELOG-Hinweis geändert werden, wenn die Änderung für Betreiber relevant ist (z. B. ein neuer Standard-Port).

Verschlüsselte Geheimnisse (at-rest)​

Das enc:-Präfixmarkierung und der Fernet-abgeleitete Schlüssel in backend/app/core/encryption.py sind innerhalb von 1.x stabil. Betreiber müssen Geheimnisse nicht über Minor-Upgrades hinweg neu verschlüsseln.

Veraltungszyklus​

Wenn etwas, das von dieser Richtlinie abgedeckt ist, entfernt werden muss:

  1. In Minor N als veraltet markieren. Der CHANGELOG-Eintrag enthält einen Deprecated-Abschnitt, der auf die Änderung hinweist. Für API-Endpunkte sendet die veraltete Route einen Deprecation: true-Antwortheader (RFC 8594) und einen Sunset-Header, der das früheste Entfernungsziel angibt.
  2. In Minor N+1 weiterhin unterstützen. Die Entfernung kann nicht im selben Minor wie die Veraltung erscheinen. Die veraltete Form funktioniert weiterhin.
  3. Früheste Entfernung in Minor N+2 oder in 2.0 (je nachdem, was zuerst kommt). Die Entfernung erfolgt mit einem Removed-Abschnitt im CHANGELOG und einem Migrationshinweis.

Für Datenformänderungen (Alembic-Migrationen) gilt dieselbe N → N+1-Kadenz, ausgedrückt als neue-hinzufügen → befüllen → alte-entfernen.

Was nicht abgedeckt ist​

Diese Punkte sind ausdrücklich außerhalb des Geltungsbereichs und können sich jederzeit ändern:

  • Das interne Python-Modullayout unter backend/app/. Importe von app.models, app.services usw. sind nicht Teil der öffentlichen API. Plugins oder Skripte, die auf interne Importe angewiesen sind, sollten eine bestimmte Canopy-Version festlegen.
  • Die Struktur von JSONB-Blobs, die auf integrierten Tabellen gespeichert sind (fields_schema, section_config, attributes, lifecycle), jenseits dessen, was von der dokumentierten REST-API gelesen wird. Die On-Disk-JSON-Form kann sich entwickeln, um neue Funktionen zu unterstützen.
  • Frontend-Interna: Komponentendateipfade, Prop-Signaturen von Komponenten in frontend/src/, der Inhalt von frontend/src/types/index.ts und das Styling von MUI-Komponenten. Betreiber, die das gebündelte Frontend verwenden, sind geschützt; wer Komponenten aus dem Quellbaum einbettet, ist auf sich allein gestellt.
  • Vom Betreiber eingeführte Metamodell-Anpassungen. Wenn Sie über die Admin-Benutzeroberfläche einen benutzerdefinierten Kartentyp oder ein benutzerdefiniertes Feld hinzufügen, liegt die Migrationsstrategie bei Ihnen.
  • Demo- und Seed-Daten (SEED_DEMO=true). Der Demo-Datensatz darf sich zwischen Releases frei weiterentwickeln.
  • Gebündelte Drittanbieter-Dienste: DrawIO-Version, gebündeltes Ollama-Image, die eingebettete swagger-ui-dist-Version. Diese können jederzeit aktualisiert werden.
  • Verhalten mit nicht standardmäßigen Konfigurationen, die in CHANGELOG-Einträgen ausdrücklich als experimentell gekennzeichnet sind.

Was 1.0.0 tatsächlich ändert​

Im Vergleich zur 0.x-Serie ist 1.0.0 selbst kein Feature-Release – es ist der Punkt, ab dem die oben genannten Verpflichtungen gelten. Der in 1.0.0 ausgelieferte Code ist derselbe Code wie in 0.71.0, ergänzt um die Supply-Chain-Härtung und Beitragsablauf-Änderungen, die im 1.0.0-CHANGELOG-Eintrag dokumentiert sind.

Releases vor 1.0 waren von dieser Richtlinie nicht abgedeckt. Migrationen zwischen 0.x-Versionen konnten und enthielten Schema-Drops, Umbenennungen und brechende Metamodell-Änderungen. Ab 1.0.0 durchlaufen diese den Veraltungszyklus.