# 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

```bash
./scripts/alanctl doctor
./scripts/alanctl backup
```

## Pflicht bei Repo-Upgrade

Wenn du das Repo selbst aktualisierst:

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

Danach erst:

```bash
./scripts/alanctl validate
./scripts/alanctl up
```

## Umgang mit `.env`

Die lokale `.env` ist betriebsrelevant und bleibt lokal.

Vor jedem Repo-Upgrade:

```bash
git diff HEAD~1 .env.example
```

oder allgemeiner:

```bash
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