alan/docs/upgrade-policy.md

Upgrade-Policy

Grundsatz

Upgrades sollen reversibel, dokumentiert und fuer eine einzelne Workstation realistisch bedienbar sein.

Klassen von Aenderungen

1. Sicheres Patch-Upgrade

Beispiele:

• Doku-Updates
• Healthcheck-Feinschliff
• nicht-invasive Skriptkorrekturen

Erwartung:

• kein manueller Eingriff noetig
• normales update-hermes reicht

2. Operatives Minor-Upgrade

Beispiele:

• neue optionale Dienste
• neue .env-Variablen mit Default
• neue Docs/Tools

Erwartung:

• Release Notes lesen
• git diff .env.example gegen lokale .env pruefen
• ggf. neuen Key ergaenzen

3. Breakendes Upgrade

Beispiele:

• Netzwerknamen aendern
• Compose-Service-Namen aendern
• persistente Pfade aendern
• State-/Datenmigrationen mit Rueckwirkungsrisiko

Erwartung:

• Backup Pflicht
• Upgrade-Fenster bewusst planen
• Rollback testen
• Release Notes muessen eine explizite Migrationsanleitung enthalten

Pflicht vor jedem geplanten Upgrade

./scripts/alanctl doctor
./scripts/alanctl backup

Pflicht bei Repo-Upgrade

Wenn du das Repo selbst aktualisierst:

git fetch --tags
git checkout <ziel-tag-oder-branch>
./scripts/release-check

Danach erst:

./scripts/alanctl validate
./scripts/alanctl up

Umgang mit .env

Die lokale .env ist betriebsrelevant und bleibt lokal.

Vor jedem Repo-Upgrade:

git diff HEAD~1 .env.example

oder allgemeiner:

git diff <alter-tag>..<neuer-tag> -- .env.example

Wenn neue Variablen eingefuehrt wurden, muessen diese in die lokale .env uebernommen werden.

Rollback-Regel

Image-Rollback und State-Rollback sind getrennt zu betrachten.

• rollback-hermes setzt das letzte bekannte gute Image wieder ein
• bei problematischer Datenmigration muss zusaetzlich ein Backup-Archiv via restore zurueckgespielt werden