# Versionierung

## Versionsnummern

FLORIAN folgt [Semantic Versioning](https://semver.org/lang/de/) in der Form
`MAJOR.MINOR.PATCH`.

Solange die Hauptversion `0` ist, gilt die Software als im Aufbau: es gibt
keine Zusage, dass eine Schnittstelle stabil bleibt.

| Stelle | wird erhöht, wenn |
|---|---|
| `MAJOR` | Bestehendes bricht — Datenmodell, REST-API unter `/api/v1` oder Konfiguration ändern sich so, dass eine bestehende Installation Handarbeit braucht. Ab `1.0.0`. |
| `MINOR` | Eine Phase ist abgeschlossen oder ein Funktionsbereich kommt hinzu. |
| `PATCH` | Fehlerbehebungen, Textkorrekturen, Abhängigkeits-Updates — alles ohne neue Funktion. |

### Zuordnung Phase zu Version

Jede abgeschlossene Phase bekommt eine Minor-Version. Das macht aus der
Versionsnummer eine Aussage über den Funktionsumfang.

| Version | Phase |
|---|---|
| `0.1.0` | Phase 0 — Fundament |
| `0.2.0` | Phase 1 — Stammdaten |
| `0.3.0` | Phase 2 — Wartung und Prüfung |
| `0.4.0` | Phase 3 — Einsätze und Übungen |
| `0.5.0` | Phase 4 — Kiosk-PWA |
| `0.6.0` | Phase 5 — Atemschutz |
| `0.7.0` | Phase 6 — Kartenmodule |
| `0.8.0` | Phase 7 — Benachrichtigungen und Termine |
| `0.9.0` | Phase 8 — Lokale KI |
| `1.0.0` | Freigabe für den Wirkbetrieb durch die Wehr |

`1.0.0` ist bewusst an die **Freigabe** gebunden, nicht an Phase 8. Erst wenn
eine Wehr die Software im Echtbetrieb einsetzt, darf die analoge Überwachung
zurücktreten — und erst dann ist eine Zusage über Stabilität ehrlich.

## Wo die Version steht

- `package.json` → `version` ist die Wahrheit.
- `CHANGELOG.md` bekommt je Version einen eigenen Abschnitt.
- Git-Tag in der Form `v0.1.0`.

```bash
npm version minor -m "Version %s — Phase 1 abgeschlossen"
git push --follow-tags
```

## Changelog

Format nach [Keep a Changelog](https://keepachangelog.com/de/1.1.0/), auf
Deutsch. Überschriften je Abschnitt:

- **Hinzugefügt** — neue Funktionen
- **Geändert** — Verhalten, das anders geworden ist
- **Veraltet** — bleibt vorerst, verschwindet aber
- **Entfernt** — ist weg
- **Behoben** — Fehlerbehebungen
- **Sicherheit** — alles, was Sicherheitsbezug hat

Einträge beschreiben, was sich für die **Wehr** ändert, nicht welche Datei
angefasst wurde. Also: „Prüfprotokolle lassen sich als PDF ablegen" statt
„PdfService ergänzt".

Was noch nicht veröffentlicht ist, sammelt sich unter `[Unveröffentlicht]` und
bekommt beim Setzen des Tags die Versionsnummer und das Datum.

## Branches

| Branch | Zweck |
|---|---|
| `main` | immer lauffähig. Tests grün, Build durch. |
| `feat/<nr>-<kurz>` | neue Funktion, `<nr>` ist die Issue-Nummer |
| `fix/<nr>-<kurz>` | Fehlerbehebung |
| `chore/<kurz>` | Aufräumen, Abhängigkeiten, Werkzeuge |

Nie direkt auf `main` committen. Jede Änderung läuft über einen Branch und
einen Pull Request.

## Commits

Deutsch, Imperativ, erste Zeile höchstens 72 Zeichen. Die letzte Zeile
verweist auf das Issue:

```
Prüfprotokoll als PDF über Gotenberg erzeugen

Das Protokoll wird nach dem Abschluss unveränderlich in MinIO abgelegt.
Korrekturen erzeugen ein neues Protokoll mit Verweis auf das ursprüngliche.

Refs #42
```

Der Text des Pull Requests enthält `Closes #42`.

## Datenbankmigrationen

- Eine Migration wird nach dem Anwenden **nie** verändert. Ein Fehler wird mit
  einer neuen Migration behoben.
- Der Ordnername sagt, worum es geht: `20260902000100_rls_policies`.
- Jede Migration beginnt mit einem Kommentarblock, der erklärt **warum** sie
  existiert — nicht nur was sie tut.
- Migrationen, die Daten verlieren können, werden im Changelog unter
  **Sicherheit** oder **Geändert** ausdrücklich genannt.

## Was vor einem Tag erledigt sein muss

1. `npm run typecheck` ohne Ausgabe
2. `npm run test` grün
3. `npm run test:e2e` grün
4. `npm run build` durch
5. `docker compose -f docker-compose.yml up -d` startet sauber
6. Changelog-Abschnitt geschrieben
7. Devlog-Eintrag mit der aufgewendeten Zeit ergänzt
8. Aufwandsschätzung um den Ist-Wert ergänzt
9. Bildschirmfotos neu erzeugt, falls sich die Oberfläche geändert hat