# Git-Arbeitsweise — verbindlich für alle Repositories

Stand 23.09.2026. Diese Regeln gelten für **jedes** Repository der Organisation `AG_Prozesse`, für Menschen und für
KI-Agenten gleichermaßen. Die Kurzfassung für den Agenten steht in `AGENTS.md`; hier steht das Vollständige mit
Begründung. Wer eine Abweichung braucht, macht ein Issue auf — nicht einfach einen Push.

> **Die goldene Regel**
>
> Auf `main` wird nicht gearbeitet. `main` nimmt ausschließlich fertige Arbeit per Pull Request entgegen.
> Gearbeitet wird in kurzlebigen Branches, die nach dem Merge gelöscht werden.
>
> **Und: Der Mensch drückt ab.** Agenten bereiten alles vor. Push, Merge und Tag macht eine Person mit ihrem
> eigenen Zugang.

## 1. Das Modell

Es gibt genau einen dauerhaften Branch: **`main`**. Er ist immer der abgenommene Stand. Alles andere sind
Arbeitsbranches, die von `main` abzweigen und per Pull Request zurückkommen (ADR 0002). Release-Kanäle wie in
AG_QGIS gibt es hier nicht, weil nichts ausgeliefert wird.

## 2. Der normale Weg

```bash
# 1. main aktualisieren (macht auch /hallo bzw. python scripts/hallo.py)
git switch main
git pull --ff-only

# 2. Eigenen Branch abzweigen
git switch -c feature/12-lane-beschriftung

# 3. In kleinen Schritten arbeiten und committen
git add .agents/skills/sn-bpmn/md_to_bpmn.py .agents/skills/sn-bpmn/test_md_to_bpmn.py
git commit -m "Lane-Beschriftung bricht lange Rollennamen um (#12)"

# 4. Prüfen
python -m pytest -q
python scripts/pruefe_umlaute.py

# 5. Push — durch den Menschen, mit dessen Zugangsdaten
git push -u origin feature/12-lane-beschriftung
```

Danach im Gitea-Browser einen **Pull Request nach `main`** öffnen, nach der Vorlage
`docs/vorlagen/pull_request.md`, mit Übergabenotiz (Skill `sn-uebergabe`).

Ein Pull Request sollte an einem Tag entstehen und in einer Viertelstunde reviewbar sein. Mehr als etwa
400 geänderte Zeilen heißt: das Issue war zu groß.

## 3. Branch-Namen

| Präfix | Beispiel | Wofür |
|---|---|---|
| `feature/` | `feature/12-lane-beschriftung` | neue Funktion, neues Prozessmodell |
| `bugfix/` | `bugfix/15-gateway-kanten` | Fehlerbehebung |
| `doku/` | `doku/glossar-bpmn` | nur Dokumentation, ohne Issue zulässig |

**Regeln für den Namen:** Kleinbuchstaben, ASCII, Bindestriche statt Leerzeichen. Keine Umlaute, kein `ß`, keine
Punkte. Issue-Nummer direkt nach dem Präfix, damit Gitea den Branch dem Ticket zuordnet.

## 4. Commit-Nachrichten

Deutsch, Präsens, erste Zeile höchstens 72 Zeichen, Issue-Nummer am Ende in Klammern.

```
Lane-Beschriftung bricht lange Rollennamen um (#12)

PICTURE schneidet Lane-Titel über 30 Zeichen ab. Der Konverter bricht
jetzt an Wortgrenzen um; kurze Namen bleiben einzeilig.
```

Was die Nachricht beantworten muss: **was** ändert sich und **warum**. Das *Wie* steht im Diff.
Nicht brauchbar: „Fix", „Update", „Änderungen", „wip".

## 5. Sitzungsbeginn

Vor dem ersten Handgriff — auch wenn es „nur schnell etwas" ist:

```bash
python scripts/hallo.py        # oder in Claude Code: /hallo
```

Das holt den Stand vom Server (`git fetch`), aktualisiert `main` per Fast-Forward, wo das gefahrlos möglich ist,
und meldet alles Übrige, ohne es anzufassen. Es merged nicht, es stasht nicht, und es fasst keine ungesicherten
Änderungen an.

## 6. Was der Agent darf und was nicht

| Der Agent darf | Der Agent darf nicht |
|---|---|
| `git fetch`, `git pull --ff-only`, `git status`, `git log`, `git diff` | `git push` in jeder Form |
| lokale Branches anlegen und wechseln | `git merge`, `git rebase` |
| `git add`, `git commit` auf einem Arbeitsbranch | `git tag` |
| Tests laufen lassen, BPMN-Dateien erzeugen | Pull Requests mergen |
| Issue- und PR-Texte als Entwurf vorbereiten | `git reset --hard`, `git push --force`, `git clean` |
| Tickets über `scripts/gitea.py` lesen | irgendetwas auf dem Gitea-Server verändern |

Das ist nicht nur eine Bitte. `.claude/settings.json` im Repo verbietet die entsprechenden Kommandos technisch;
der Agent bekommt eine Ablehnung statt einer Ausführung. Wer die Regel für einen Einzelfall aussetzen will, tut
das bewusst und lokal, nicht im Repo.

**Warum so streng:** Ein Push trägt den Namen einer Person und ihre Verantwortung. Ein Agent kann fachlich nicht
beurteilen, ob ein Prozessmodell abgenommen ist — und ein versehentlicher Push auf `main` trifft sofort alle
anderen Behörden.

## 7. Branch-Schutz auf Gitea einrichten (Maintainer)

Je Repository unter **Einstellungen → Branches** (englisch: *Settings → Branches*) eine Branch-Schutzregel für
`main` anlegen:

| Einstellung | Wert | Wirkung |
|---|---|---|
| Branch-Name | `main` | betrifft genau diesen Branch |
| Push deaktivieren | an | kein direkter Push, nur Merge über Pull Request |
| Merge-Freigabe erforderlich | mindestens 1 | Review durch eine andere Person ist Pflicht |
| Veraltete Freigaben verwerfen | an | ein neuer Push macht das Review ungültig |

**Ausnahme beim Anlegen:** Der allererste Stand eines neuen Repositorys wird direkt nach `main` gepusht, weil es
vorher nichts gibt, wogegen ein Pull Request laufen könnte. Die Schutzregel danach setzen.

## 8. Aufräumen

Nach dem Merge wird der Arbeitsbranch gelöscht — in Gitea per Schaltfläche direkt am gemergten Pull Request,
lokal so:

```bash
git switch main
git pull --ff-only
git branch -d feature/12-lane-beschriftung
git fetch --prune
```

## 9. Häufige Fehler

**„Ich habe direkt auf `main` committet."** Solange nichts gepusht ist, ist das reparabel:
`git switch -c feature/<nr>-<name>` legt einen Branch auf dem aktuellen Stand an, danach
`git switch main && git reset --hard origin/main`. Der `reset` ist hier zulässig, weil er nur die lokale
Kopie auf den Serverstand zurücksetzt — trotzdem vorher `git log` prüfen.

**„Mein Branch ist hinter `main`."** Vor dem Pull Request aktualisieren:
`git switch main && git pull --ff-only`, dann zurück auf den Arbeitsbranch und `git merge main`.
Kein `rebase` auf bereits gepushten Branches — das schreibt Historie um, die andere schon haben.

**„`git pull` will einen Merge-Commit machen."** Dann ist der lokale Branch vorausgelaufen. `--ff-only` bricht
in dem Fall bewusst ab. Erst klären, was die eigenen Commits sind, statt blind zu mergen.

## Siehe auch

- `AGENTS.md` — Kurzfassung der harten Regeln
- `docs/leitfaden/03_arbeitsweise.md` — der Arbeitszyklus vom Issue bis zum Merge
- `docs/entscheidungen/0002-branchmodell-main.md` — warum das Modell so aussieht