---
type: Guide
status: ACTIVE
owner: Lead Architect
last_update: 2026-04-28
---

# Git Branching & Deployment Strategy (Meldestelle)

Um parallele Weiterentwicklung und stabile Feld-Tests zu ermöglichen, nutzen wir einen vereinfachten **GitHub Flow** mit Release-Tags. Da wir ein kleines Team (bzw. Solo-Entwickler mit KI-Agents) sind, verzichten wir auf übermäßig komplexe Git-Flow-Modelle (wie `develop`, `release/*`, `hotfix/*`), stellen aber Stabilität für Deployments sicher.

## 1. Branching-Struktur

### `main` (Source of Truth / Production)
*   **Zweck:** Enthält *immer* den aktuellen, stabilen und im Feld getesteten/auslieferbaren Code.
*   **Regel:** Direkte Commits auf `main` sind tabu (außer Notfall-Hotfixes).
*   **Deployment:** Ein Push/Merge auf `main` bedeutet **nicht** zwingend ein sofortiges Deployment auf Zora, aber der Code ist *bereit* dafür.

### Feature Branches (`feature/*` oder `fix/*`)
*   **Zweck:** Hier findet die eigentliche Entwicklung statt (z.B. neue Bounded Contexts, Wizards).
*   **Namenskonvention:** `feature/event-wizard-neu`, `fix/zns-import-bug`
*   **Lebensdauer:** So kurz wie möglich. Sobald ein Feature/Fix *in sich geschlossen* und lokal getestet ist, wird ein Pull Request (PR) auf `main` erstellt.

### Release Tags (`v1.x.x`)
*   **Zweck:** Markiert einen spezifischen, stabilen Punkt auf dem `main`-Branch, der tatsächlich für ein Turnier (Feld-Test) deployed wurde.
*   **Szenario:** Du hast Version `v1.2.0` (Plan-B) für ein Turnier deployed. Du entwickelst weiter auf `feature/*` und mergest in `main`. Das nächste Turnier bekommt dann Tag `v1.3.0`.

## 2. Der Workflow im Alltag

1.  **Start:** `git checkout main` -> `git pull` -> `git checkout -b feature/mein-neues-feature`
2.  **Entwicklung:** Arbeiten, KI-Agents nutzen, Commits machen.
3.  **Abschluss:** Feature ist fertig.
4.  **Merge:** Pull Request in Gitea erstellen (oder lokal: `git checkout main`, `git merge feature/mein-neues-feature`, `git push`).
5.  **Aufräumen:** `git branch -d feature/mein-neues-feature`

## 3. Strategie für Feld-Tests (Turnier-Einsatz)

Wenn ein Turnier ansteht und ein stabiler Stand eingefroren werden muss:

1.  Stelle sicher, dass `main` den gewünschten Zustand hat.
2.  Setze einen Tag in Git: `git tag -a v1.2.0 -m "Release für Turnier in Neumarkt"`
3.  Pushe den Tag: `git push origin v1.2.0`
4.  **Deployment:** Das Deployment-Skript zieht sich *diesen* Tag auf Zora (oder baut den Docker-Container aus diesem Tag).

### Was passiert, wenn während des Turniers ein Bug auftritt (Hotfix)?

*Szenario: Das Turnier läuft auf `v1.2.0`. Auf `main` gibt es schon neuere Features (unfertig).*

1.  Checkout des stabilen Tags: `git checkout -b hotfix/turnier-fix v1.2.0`
2.  Bug fixen, committen.
3.  Neuen Tag für das Deployment setzen: `git tag -a v1.2.1 -m "Hotfix ZNS Import"`
4.  `git push origin v1.2.1` -> Fix wird auf Zora deployed.
5.  **WICHTIG (Backport):** Damit der Fix nicht verloren geht, den Hotfix-Branch danach in `main` mergen: `git checkout main`, `git merge hotfix/turnier-fix`.

## 4. Gitea Actions (CI/CD)
*   **Pushes auf `feature/*`:** Führen Code-Checks/Tests aus.
*   **Pushes auf `main`:** Führen erweiterte Tests aus und bauen Docker-Images mit dem Tag `latest` sowie dem Git-SHA in die interne Registry (`10.0.0.22:3000`).
*   **Erstellung eines Tags (`v*`):** Triggert automatisch den Build und Push von Docker-Images in die interne Registry. Das Image erhält den Namen des Tags (z.B. `:v1.2.0`). Dies ist die Basis für stabile Deployments auf Zora.