# Git Workflow & Deployment Specification

Dieses Dokument beschreibt den standardisierten Release-Ablauf und die CI/CD-Logik für Gitea.

---

## 1. Branching-Modell

Wir nutzen einen vereinfachten, stabilen Release-Workflow mit zwei Haupt-Branches:

* **`main` (Development / Spielwiese):**
  * Tägliche Entwicklung, Experimente, lokale Tests (venv / local Docker).
  * Änderungen werden direkt hier committet oder aus Feature-Branches hineingemergt.
* **`stable` (Production / Freeze):**
  * Spiegelt exakt den Live-Stand der Produktion wider.
  * Direct Commits sind tabu. Änderungen gelangen **ausschließlich per Merge aus `main`** hierhin.

---

## 2. Release-Ablauf (Dev nach Prod)

Sobald ein Stand auf `main` lokal getestet und einsatzbereit ist:

### Variante A: Via Terminal (CLI)
```bash
# 1. Lokalen Stand auf main sichern
git checkout main
git pull

# 2. Auf stable wechseln und main hineinmergen
git checkout stable
git merge main

# 3. Release nach Gitea pushen (Triggert CI/CD)
git push origin stable

# 4. Zurück auf main für die weitere Entwicklung
git checkout main

```

### Variante B: Via VSCodium Git-UI

1. Unten links den Branch von `main` auf `stable` wechseln.
2. Befehlspalette öffnen (`Ctrl + Shift + P`) -> `Git: Branch mergen...` -> **`main`** auswählen.
3. Auf **Änderungen synchronisieren** (Push) klicken.
4. Unten links wieder zurück auf **`main`** wechseln.

---

## 3. Gitea Runner & Deployment Logic

Der Rebuild auf dem Produktionsserver wird vollautomatisch über Gitea Actions getriggert.

* **Trigger:** Das Deployment startet **nur**, wenn Änderungen auf den Branch `stable` gepushed werden.
* **Workflow-Datei:** `.gitea/workflows/deploy.yml`

### `.gitea/workflows/deploy.yml` Template:

```yaml
name: Production Deployment

on:
  push:
    branches:
      - 'stable'

jobs:
  deploy:
    runs-on: self-hosted
    steps:
      - name: Checkout Code
        uses: actions/checkout@v3

      - name: Rebuild & Restart Docker Containers
        run: |
          docker compose down
          docker compose up --build -d --pull always
          docker image prune -f

```

---

## 4. Regeln für AI-Agenten (Vibe / Roo Code)

* Agenten arbeiten **ausschließlich auf dem `main`-Branch**.
* Agenten dürfen niemals eigenständig einen Merge auf `stable` durchführen oder Commits auf `stable` pushen.
* Das Erstellen von `.env` Dateien auf `stable` ist untersagt (Nutzung der Server-Umgebungsvariablen via `.env.example`).

```

---