Versionierung¶

Vesana folgt Semver mit klaren Spielregeln.

Schema¶

MAJOR.MINOR.PATCH

Sprung	Was passiert	Rollback möglich?
Patch (0.19.0 → 0.19.1)	Bug-Fixes, keine Schema-Änderungen	Ja, frei
Minor (0.18.x → 0.19.0)	Neue Features, additive Migrationen	Ja, bedingt
Major (0.x.y → 1.0.0)	Breaking-Changes nach Deprecation	Nein

Versionsformat¶

v-Prefix in Tags und VERSION-Dateien: v0.19.0, nicht 0.19.0.

In API-Responses (X-Vesana-Version) und Frontend-Build kommt der nackte Wert ohne v.

Migrationen¶

Additivität¶

Migrations dürfen:

neue Tabellen anlegen
neue Spalten hinzufügen (mit DEFAULT oder NULLABLE)
neue Indexes anlegen
neue Builtin-Daten via UPSERT seeden

Migrations dürfen nicht in einem Minor:

Spalten löschen
Tabellen löschen
NOT-NULL ohne Default einführen
bestehende Spalten umbenennen
Daten-Operationen, die vorhandene Werte zerstören

Was zerstörerisch sein muss, kommt in einer Major-Migration mit Deprecation-Vorlauf.

Beispiel-Deprecation¶

v0.19.0 — agent_managed-Spalte als deprecated markiert (Code schreibt nicht mehr rein, liest aber noch)
v0.20.0 — Code liest nicht mehr, Spalte bleibt
v1.0.0 — Migration droppt die Spalte

Mindestens 2 Major-Releases zwischen „nicht mehr genutzt" und „gedroppt".

Rollback-Fenster¶

Innerhalb eines Minors ist Rollback frei. Beispiel:

0.19.3 → 0.19.4 → 0.19.5 — alles rollback-fähig
0.19.5 → 0.20.0 — Rollback bedingt möglich, neue Spalten bleiben aber leer

Bei Major-Updates: kein Rollback. Vorher Backup, vorher testen.

Auto-Update-Verhalten¶

Der GUI-Updater hat einen Channel:

Channel	Was er installiert
`stable` (Default)	nur Stable-Releases (geprüft, dokumentiert)
`beta`	RC-Versionen vor Stable
`pinned:vX.Y.Z`	nur diese exakte Version, kein Auto-Update

Setzbar in .env: VESANA_UPDATE_CHANNEL=stable.

Pre-Release-Tags¶

Tag	Bedeutung
`0.19.0-rc.1`	Release-Candidate
`0.19.0-beta.1`	offene Tester
`0.19.0-dev`	unstetig, nicht für Production

stable-Channel überspringt Pre-Releases.

Breaking-Changes — Politik¶

Nicht jeder Change ist breaking. Die Definition:

Breaking ist ein Change, der dazu führt, dass:

bestehende API-Clients mit identischem Code Fehler bekommen
bestehende Agents/Collectors nicht mehr funktionieren
bestehende Configs ungültig werden ohne Migration

Nicht-breaking:

neue optionale Felder
neue Endpoints
mehr Detail in Error-Responses
neue UI-Pfade
neue Permissions (Default-Rollen kriegen sie automatisch)

Bei Breaking-Changes: Major-Release, Deprecation-Phase mindestens ein Minor vorher, Migrations-Anleitung im Changelog.

API-Versionierung¶

/api/v1/ ist stabil. Wenn /api/v2/ käme, würde es:

parallel zu v1 laufen mindestens 2 Major-Releases
v1-Endpoints Deprecation-Header senden
Migrations-Doku pro Endpoint

Aktuell ist nur v1 in Sicht.

Frontend-Versionierung¶

Frontend-Bundle wird mit jedem Server-Update mit-deployed. Es gibt keine API-Version-Bindung — das Frontend nutzt v1 immer.

Bei größeren Frontend-Änderungen: Cache-Buster im Build-Hash, alte Tabs zeigen einen „Bitte neu laden"-Banner.

Agent / Collector-Versionierung¶

Agent / Collector haben eigene Versionen unabhängig vom Server. Auto-Update bringt sie auf die vom Server bereitgestellte VERSION.

Kompatibilität: jeder Agent/Collector ≥ vorletzten Major-Release sollte mit jedem Server kompatibel sein. Ältere Versionen melden sich mit Warning, funktionieren aber.

Wie wir Releases machen¶

flowchart LR
    DEV[Feature-PR]
    DEV --> MERGE[Merge auf main]
    MERGE --> CI[CI: Tests + Build]
    CI --> TAG[git tag v0.X.Y]
    TAG --> RELEASE[GitHub-Release mit Notes]
    RELEASE --> GHCR[Image-Push GHCR]
    GHCR --> LP[Lizenzportal published]
    LP --> END[Self-Hoster sehen Update-Banner]

Pro Release: ausführliche Notes, Migrations-Hinweis falls relevant, Breaking-Changes (falls Major) prominent oben.

Wie wir mit Hotfixes umgehen¶

Bei kritischen Bugs:

Patch-Branch von letztem Stable-Tag
Fix-Commit
vX.Y.(Z+1) Tag
Schnell-Release ohne Wartezeit auf nächstes geplantes Update
GUI-Updater zeigt sofort verfügbar

Hotfixes sind explizit gekennzeichnet im Changelog ((hotfix)).