meldestelle/docs/02_Guides/Git_Branching_Strategy.md

type, status, owner, last_update

type	status	owner	last_update
Guide	ACTIVE	Lead Architect	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.