Updates & Upgrades

TeamVis folgt Semantic Versioning (MAJOR.MINOR.PATCH).

Versionsschema

Sprung	Bedeutung	Was du tun musst
Patch (1.0.0 → 1.0.1)	Bugfix, kein Schema-Change	docker compose pull && up -d
Minor (1.0.0 → 1.1.0)	Feature, Schema-Change möglich	DB-Migration einspielen, dann Container-Update
Major (1.0.0 → 2.0.0)	Breaking Change	Migration-Notes lesen, Backup, dann Update

Patch-Releases sind immer rückwärtskompatibel mit der DB-Version. Minor- und Major-Releases können neue Migrations bringen — die liegen im Repo unter supabase/migrations/.

Standard-Update-Prozess

cd /opt/teamvis

# 1. Backup
pg_dump "$DATABASE_URL" --format=custom > /backup/teamvis-pre-update.dump

# 2. Release-Notes lesen
#    https://git.zoesch.de/zfx-services/teamvis/releases

# 3. Falls Migrations fehlen: einspielen (Supabase SQL Editor oder psql)
#    Alle in supabase/migrations/ mit höherer Nummer als der aktuell
#    eingespielten

# 4. Image ziehen + Container neu starten
docker compose pull
docker compose up -d --force-recreate

Was ist ein „Breaking Change”?

• DB-Schema-Änderung, die NICHT additiv ist (Spalte umbenannt, Tabelle gelöscht)
• ENV-Variable, die zwingend gesetzt werden muss (vorher optional)
• Endpunkt-Bruch (z. B. /api/old-route → /api/new-route)

Diese werden im Changelog prominent markiert. Vor einem Major-Update immer einen Restore-Test mit dem Backup machen — siehe Backup.

Changelog-Disziplin

Im Repo unter CHANGELOG.md. Pro Version:

## v1.1.0 — 2026-06-15

### Added
- Self-Service-Portal mit Magic-Link-Auth
- Webhook-Subscriptions mit HMAC-Signatur

### Changed
- Compliance-Modul: Bindings nutzen jetzt position_id statt employee_id
  (Migration 0009_compliance.sql notwendig)

### Fixed
- Trusted-Token-Leak via anon-Key (CVE-Like, sicherheitsrelevant)

### Migration-Notes
- DB-Migrations 0008-0010 vor Container-Start einspielen
- ENV-Variable `SESSION_SECRET` muss jetzt ≥32 Zeichen sein

Folgt dem Keep a Changelog-Format. Sicherheits- und Migrations-Notes immer separat hervorheben.

Release-Cycle

Release-Typ	Frequenz	Beispiel
Patch	bei Bedarf, kritische Bugs sofort	1.0.x
Minor	~6-8 Wochen	1.1.0, 1.2.0
Major	nach Bedarf, mindestens 6 Monate Vorankündigung	2.0.0

LTS-Versionen sind in Vorbereitung — eine Major-Version wird mindestens 12 Monate lang mit Security-Patches versorgt, auch wenn die nächste Major schon da ist.

Update-Channel-Optionen

Zwei Tag-Pfade in der Registry:

• :<version> (z. B. :1.2.3) — pinned auf eine konkrete Version. Empfohlen für Production
• :latest — zieht immer den letzten Release. Bequem für Test-/Dev- Instanzen, riskant für Production weil ein compose pull ungewollt einen Major-Sprung machen kann

Empfehlung: Production auf :<version> pinnen, Updates bewusst auslösen.

Rollback

docker compose pull git.zoesch.de/zfx-services/teamvis:<vorherige-version>
# Edit docker-compose.yml: image-Tag zurück auf alte Version
docker compose up -d --force-recreate

# Falls Schema-Migration eingespielt war und nicht rückwärtskompatibel:
psql "$DATABASE_URL" < /backup/teamvis-pre-update.dump

DB-Rollback ist heikel — daher der Pre-Update-Backup-Schritt. Nach Rollback sind Daten zwischen Update und Rollback verloren, sofern du keine inkrementellen Backups hast.

Was wir versprechen

• Patch + Minor sind immer DB-rückwärtskompatibel — d. h. das alte Image läuft mit der neuen DB. Du kannst Container und DB unabhängig updaten
• Major-Releases haben einen Übergangs-Pfad — alte Tabellen werden mit Migration in neue umstrukturiert, Daten gehen nicht verloren
• Breaking Changes kündigen wir mindestens 1 Minor-Release vorher an (z. B. „in v1.5 wird Feature X deprecated, in v2.0 entfernt”)

Was wir nicht versprechen

• Auto-Updates oder Selbst-Update-Dialoge im UI — Updates laufen explizit per docker compose pull
• Cross-Major-Migrations (z. B. v1 → v3) ohne Zwischenschritte — wir testen nur sequentielle Migrations
• Production-Restores aus 5 Jahre alten Dumps — Postgres-Versionen werden weiterentwickelt, ältere pg_dump-Formate haben Kompatibilitätsgrenzen