Zum Hauptinhalt springen

Releases und Vorabversionskanal

Wie Canopy Versionen verwaltet, Tags setzt und Container-Images veröffentlicht. Diese Seite ist die Referenz für Betreiber, die Versionen in der Produktion festlegen müssen, sowie für Mitwirkende, die Releases erstellen.

Versionierung​

Canopy folgt Semantic Versioning. Die einzige Quelle der Wahrheit für die aktuelle Version ist die Datei /VERSION im Repo-Root.

  • Patch (z. B. 1.0.0 → 1.0.1): Nur Fehlerbehebungen. Immer sicher zum Upgrade.
  • Minor (z. B. 1.0.0 → 1.1.0): Neue Funktionen. Abwärtskompatibel gemäß der Kompatibilitätsrichtlinie.
  • Major (z. B. 1.x → 2.0.0): Brechende Änderungen. Migrationshinweise werden mit dem Release ausgeliefert.

Die Version wird einmal pro PR erhöht, nicht pro Commit. Der CHANGELOG-Eintrag des PRs verwendet die neue Version als Überschrift; der CI-Workflow version-check.yml lässt jeden PR fehlschlagen, der VERSION erhöht, ohne eine passende ## [<version>]-Überschrift in CHANGELOG.md zu haben.

Container-Image-Tags​

Jeder Push zu main und jedes v*.*.*-Tag löst .github/workflows/docker-publish.yml aus, das Multi-Arch-Images (amd64 + arm64) erstellt und in GHCR veröffentlicht.

Für ein Release-Tag wie v1.2.3 sind die veröffentlichten Tags für jedes Image:

TagZeigt aufStabil?
1.2.3genau dieses Releaseja – diesen in der Produktion festlegen
1.2neuester Patch auf 1.2.xrollt bei Patches vorwärts
1neuester Minor auf 1.xrollt bei Minors vorwärts
latestneuestes Nicht-Vorab-Releaserollt bei jedem Release vorwärts
sha-<short>exakter Commitja – Debugging / Vorabversion

Bei Pushes zu main (ohne Tag) werden nur die Tags main und sha-<short> erzeugt – niemals latest, niemals ein Semver-Tag.

Alle veröffentlichten Image-Manifeste werden mit cosign und keylosem OIDC signiert. Verifizierungs- und SBOM-Details finden sich unter Supply Chain.

Vorabversionskanal​

Für Minors, die Container-Layout, Basis-Images, Standard-UIDs, Volume-Namen, Standard-Ports oder Schemata auf eine Weise ändern, die Betreibermaßnahmen erfordert, wird vor dem endgültigen Tag ein Release Candidate erstellt.

Konventionen:

  • RC-Tags sind vX.Y.0-rc.N – niemals auf einem Patch-Release, nur auf Minors mit für Betreiber sichtbaren Änderungen.
  • Die docker/metadata-action des Publish-Workflows ist mit flavor: latest=auto konfiguriert. Dies schließt automatisch Vorabversions-Semver-Tags von :latest, :X.Y und :X aus – RCs werden nur als :X.Y.0-rc.N veröffentlicht. Betreiber, die an :latest festhalten, ziehen versehentlich keinen RC.
  • Das GitHub-Release für ein RC-Tag sollte auf der Releases-Seite als Vorabversion markiert werden. Der aktuelle github-release.yml-Workflow erstellt immer ein Nicht-Vorabversions-Release; der Betreuer schaltet das Vorabversions-Kontrollkästchen manuell um, nachdem der Workflow ausgeführt wurde (oder bearbeitet das Release über gh release edit vX.Y.0-rc.N --prerelease).

Reifezeit:

  • Ein RC bleibt mindestens 48–72 Stunden aktiv, bevor er hochgestuft wird, oder bis mindestens ein Betreiber außerhalb des Betreuers ein erfolgreiches Upgrade meldet – je nachdem, was länger dauert.
  • Fehlerberichte zu einem RC werden als vX.Y.0-rc.N+1 ausgeliefert, wenn das Problem behebungswürdig ist. Der vorherige RC bleibt zur Reproduzierbarkeit in GHCR.

Hochstufung auf final:

  • Das endgültige vX.Y.0-Tag wird auf demselben Commit wie der letzte RC erstellt. Der Publish-Workflow erstellt Multi-Arch-Images neu und setzt neue Tags; der Digest unterscheidet sich vom RC, auch wenn der Quellcode identisch ist (Build-Eingaben umfassen Zeitstempel).
  • Die Tags :X.Y, :X und :latest zeigen ab diesem Zeitpunkt auf das finale Release.

Release erstellen (Betreuer-Checkliste)​

Für einen normalen Patch oder Minor – kein RC-Kanal erforderlich:

  1. Auf einem Feature-Branch VERSION erhöhen und die passende ## [<version>] - YYYY-MM-DD-Überschrift zu CHANGELOG.md hinzufügen.
  2. python scripts/dump_openapi.py ausführen, wenn sich eine Backend-Route oder ein Schema geändert hat; das Ergebnis committen, falls es sich geändert hat.
  3. PR öffnen. CI führt Lint, Tests, OpenAPI-Drift-Prüfung und version-check.yml aus.
  4. Squash-Merge zu main.
  5. Von main aus: git tag -s v<version> -m "v<version>" (oder git tag v<version>, wenn kein Signing-Key konfiguriert ist), git push origin v<version>.
  6. Der Workflow Publish GitHub Release extrahiert den ## [<version>]-Abschnitt aus CHANGELOG.md und erstellt ein GitHub-Release.
  7. Der Workflow Publish Docker images to GHCR erstellt, signiert und veröffentlicht die Multi-Arch-Images.
  8. Mit cosign verifizieren: 
    cosign verify \
      --certificate-identity-regexp 'https://github.com/Rhizo-Tech/canopy/.+' \
      --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
      ghcr.io/rhizo-tech/canopy/backend:<version>

Für einen Minor, der einen RC erfordert:

  1. Derselbe PR-und-Merge-Ablauf wie oben, aber zu 1.Y.0-rc.1 erhöhen.
  2. Nach dem Merge v1.Y.0-rc.1 taggen und pushen. Der Publish-Workflow erstellt und veröffentlicht die RC-Images (nur :1.Y.0-rc.1, niemals :latest oder Kurz-Tags – flavor: latest=auto übernimmt das). Der Release-Workflow erstellt ein GitHub-Release; danach manuell auf Vorabversion umschalten via gh release edit v1.Y.0-rc.1 --prerelease oder in der GitHub-Benutzeroberfläche.
  3. Reifezeit abwarten. Gemeldete Probleme mit -rc.2, -rc.3 usw. beheben.
  4. Zur Hochstufung: VERSION in einem finalen PR auf 1.Y.0 erhöhen (CHANGELOG-Eintrag konsolidiert alle RC-Fixes), mergen, v1.Y.0 taggen, pushen. Die Tags :latest und Kurz-Tags zeigen nun auf das hochgestufte Release.

End-of-Life​

Nur die neueste Minor-Linie erhält Sicherheitsfixes. Siehe SECURITY.md für die vollständige Richtlinie. Ältere Minor-Linien sind End-of-Life und erhalten keine Backports – Betreiber auf älteren Versionen sollten Upgrades gemäß der Kompatibilitätsrichtlinie planen.