Projektwissen/docs/leitfaden/05_git_arbeitsweise.md

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

# 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:

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:

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