# Release-Prozess

## Ziel

Dieses Repo soll sich wie ein kleines Infrastrukturprodukt pflegen lassen:

- Aenderungen gesammelt entwickeln
- lokal validieren
- in Gitea taggen
- Releases mit klaren Upgrade-Hinweisen veroeffentlichen

## Versionsschema

Empfohlen: semantische Versionierung fuer das Repo.

- `MAJOR`: inkompatible Struktur- oder Betriebswechsel
- `MINOR`: neue Features oder neue Betriebsfaelle ohne harte Brueche
- `PATCH`: Fixes, Doku, sichere Defaults, kleinere Skriptanpassungen

Beispiele:

- `v0.1.0` erste stabile Struktur
- `v0.2.0` neue optionalen Dienste oder neue Netzvarianten
- `v0.2.1` Bugfix im Update-/Backup-Verhalten

## Maintainer-Ablauf

1. Feature- oder Fix-Branch bauen
2. lokal testen
3. `CHANGELOG.md` aktualisieren
4. bei Upgrade-Auswirkungen `docs/upgrade-policy.md` pflegen
5. Merge nach `main`
6. Release-Tag setzen
7. Release Notes in Gitea anlegen

## Lokale Checks vor einem Release

```bash
./scripts/release-check
./scripts/alanctl validate
./scripts/alanctl doctor
```

Optional auf einem echten Host:

```bash
./scripts/alanctl backup
./scripts/alanctl up --dashboard
./scripts/alanctl update-hermes
```

## Tagging

```bash
git checkout main
git pull --ff-only
git tag -a v0.1.1 -m "alan-agents-workstation v0.1.1"
git push origin main --tags
```

## Inhalt guter Release Notes

- Was ist neu?
- Was ist gefixt?
- Muss `.env` angepasst werden?
- Gibt es ein neues Netzwerk-/Volume-/Port-Verhalten?
- Ist ein manuelles Backup vor Upgrade empfohlen?
- Gibt es ein Rollback-Risiko bei State-Migrationen?

## Release-Text vorbereiten

Nutze `docs/release-template.md` als portable Vorlage fuer die Release-Beschreibung in Gitea.

Empfohlener Ablauf:

1. `./scripts/new-release <version>` ausfuehren
2. `CHANGELOG.md` finalisieren
3. Release-Text aus `docs/release-template.md` kopieren und auf den konkreten Stand anpassen
4. Tag pushen und Release in Gitea anlegen