git-coda – Ein-Klick Ship-Workflow

git-coda — Ein-Klick Ship-Workflow

git-coda ist der Projektname; coda (Finale) ist der Abschlusssatz eines Musikstücks, der die gesamte Entwicklungsgeschichte zu einer Note zusammenfasst und auf main zurückführt. Das Verb für den Workflow bleibt „ship“.

Ziel und Erfolgskriterien

Die Änderungen im aktuellen Arbeitsverzeichnis vollständig durch diesen Pfad führen:

Aktuelle Änderungen → Neuen Branch basierend auf dem neuesten main erstellen → committen → PR → Squash-Merge → zurück zu main

Der Aufruf von ship durch den Benutzer autorisiert die gesamte Workflow-Ausführung. Der Ablauf soll kontinuierlich erfolgen; es darf keine Bestätigungen für Branch-Namen, Commit-Nachrichten, PR-Titel, PR-Body, Konfliktlösungen, Validierungsergebnisse oder die Fortsetzung geben.

Diese Autorisierung umfasst:

• Ändern des aktuellen Funktionscodes, um ihn mit den aktuellen Online-Funktionen des neuesten main kompatibel zu machen.
• Beheben von Test-, Lint-, Typ-, Build- und CI-Problemen, die durch die aktuellen Änderungen oder Konflikte entstehen.
• Erstellen notwendiger Fix-Commits und erneutes Pushen.
• Synchronisieren mit dem neuesten main vor dem Merge, Lösen neu entstandener Konflikte und erneutes Validieren.

Der Vorgang ist nur abgeschlossen, wenn alle folgenden Bedingungen erfüllt sind:

1. Der PR wurde erfolgreich in main gemergt; „PR erstellt“ oder „Auto-Merge aktiviert“ zählt nicht als Abschluss.
2. Erforderliche Checks sind bestanden, oder das Repository hat keine ausführbaren Checks.
3. Lokal zurück zu main gewechselt und so weit wie möglich auf den gemergten Commit fast-forwarded.

Kernausführungsprinzipien

• Das Standardergebnis von ship ist „Veröffentlichung erfolgreich“, nicht „Problem gefunden und an Benutzer zurückgegeben“.
• Nach einem Befehlsfehler zuerst die Ursache diagnostizieren und den Ablauf wiederherstellen; nicht denselben fehlgeschlagenen Befehl mechanisch wiederholen.
• Die aktuellen Online-Funktionen von origin/main und das Produktziel der aktuellen Änderungen als gemeinsame Randbedingungen verwenden; beide priorisieren.
• Die Grundursache beheben; keine falschen Erfolge durch Überspringen von Tests, Löschen von Assertions, Deaktivieren von Regeln oder Verwendung von --no-verify erzeugen.
• Keine destruktiven Mittel wie Force Push, reset --hard, Verwerfen von Commits oder Überschreiben von Benutzeränderungen einsetzen.
• Nur bei fehlender Authentifizierung/Berechtigung, erforderlicher Fremdfreigabe, dauerhaft nicht verfügbarer Plattform/Netzwerk oder wenn die Anforderungsabsicht tatsächlich nicht aus Code und Kontext ableitbar ist, pausieren und die einzig erforderliche Benutzeraktion klar benennen.

Schritt 0: Informationssammlung

Vor Beginn den aktuellen Zustand prüfen:

git status --short --branch
git branch --show-current
git diff --stat
git diff --cached --stat
git remote -v
gh auth status

Gleichzeitig den aktuellen Branch, nicht committete Änderungen und nicht gepushte Commits protokollieren, um Benutzerarbeit nicht zu verlieren. Wenn es keine uncommitteten Änderungen gibt, prüfen, ob es relativ zu origin/main noch zu veröffentlichende Commits auf dem aktuellen Branch gibt; wenn beides fehlt, melden, dass nichts zu veröffentlichen ist, und anhalten.

Folgende Informationen automatisch bestimmen:

1. Branch-Name

• Wenn Benutzer bereits bereitgestellt hat, direkt verwenden.
• Andernfalls aus den Änderungen ableiten, Format <type>/<short-desc>.
• Den Branch-Präfix oder die Namenskonvention des Ziel-Repositorys befolgen; falls keine Konvention vorhanden, semantischen Namen verwenden.
• Wenn lokal oder remote bereits ein Branch mit demselben Namen existiert, automatisch einen kurzen Suffix hinzufügen, um Unterbrechungen durch Namenskonflikte zu vermeiden.

2. Commit-Nachricht

• Wenn Benutzer bereits bereitgestellt hat, direkt verwenden.
• Andernfalls aus dem vollständigen Diff im Conventional Commits-Format generieren: <type>(<scope>): <description>.

3. PR-Titel und PR-Body

• PR-Titel standardmäßig die Commit-Nachricht.
• PR-Body automatisch aus dem Diff generieren: 2–3 Zusammenfassungspunkte, Übersicht der geänderten Dateien und Validierungsergebnisse.
• Nicht separat nach PR-Name oder PR-Body fragen.

Nach der Bestimmung den Benutzer kurz über den verwendeten Branch und Commit informieren, dann sofort fortfahren, ohne auf eine Antwort zu warten.

Schritt 1: Hauptbranch synchronisieren

Wenn Arbeitsbereichsänderungen vorhanden sind, zuerst einen Stash mit eindeutigem Identifier erstellen und die zugehörige Referenz protokollieren; bei keinen Änderungen keinen leeren Stash anlegen.

git stash push --include-untracked -m "git-coda: <timestamp>"
git fetch --prune origin

Nach dem fetch anhand des in Schritt 0 protokollierten Original-Branches und Original-HEAD prüfen, ob unveröffentlichte Commits vorliegen. Wenn der originale Funktionsbranch bereits Commits enthält, diesen Branch behalten, origin/main direkt mergen und dann den aktuellen Stash wiederherstellen; nicht zuerst zu main wechseln, um zu entscheiden, ob der Original-Branch Commits hat. Nur wenn der Original-Branch keine unveröffentlichten Commits hat, von origin/main einen neuen Veröffentlichungsbranch erstellen.

Zuerst den Ziel-Hauptbranch anhand des Remote-HEAD oder der Repository-Konfiguration prüfen; unten ist main ein Platzhalter; bei Verwendung von master oder anderen Namen im Repository durch den tatsächlichen Branch ersetzen.

Den Benutzer über den Commit-Hash des neuesten Hauptbranches informieren.

Wenn lokales main nicht fast-forward kann:

1. Lokale exklusive Commits prüfen, sie nicht löschen oder überschreiben.
2. Direkt vom neuesten origin/main einen Veröffentlichungsbranch erstellen und den Veröffentlichungsprozess fortsetzen.
3. Beim endgültigen Zurückkehren zu main diese lokalen Commits behalten und klarstellen, dass lokales main nicht überschrieben wurde; dies beeinträchtigt den bereits abgeschlossenen Online-Merge nicht.

Schritt 2: Branch erstellen

git checkout -b <branch-name> origin/main

Wenn die aktuelle Arbeit bereits auf einem Funktionsbranch mit unveröffentlichten Commits liegt, kann dieser weiterverwendet werden; zuerst das neueste origin/main mergen und Konflikte nach dem „Konfliktbehandlungsprozess“ lösen. Nicht dieselben Änderungen erneut committen.

Schritt 3: Änderungen wiederherstellen und committen

git stash apply <recorded-stash>
git add -A
git commit -m "<commit-message>"

Wenn bei stash apply Konflikte auftreten, nach dem „Konfliktbehandlungsprozess“ selbstständig lösen. Nachdem sichergestellt ist, dass alle Änderungen wiederhergestellt und committet wurden, den für diesen Vorgang erstellten Stash löschen; keinen vorhandenen Benutzer-Stash versehentlich löschen.

Ein Fehler des Commit-Hooks gilt als Validierungsfehler: Grundursache beheben, erneut stagen und erneut committen, nicht --no-verify verwenden.

Konfliktbehandlungsprozess

Der folgende Prozess gilt für stash apply, Mergen des neuesten main, nicht fast-forwardbare Remotebranches und PR-Merge-Konflikte.

1. Fakten sammeln:

   git status
   git diff --name-only --diff-filter=U
   git log --oneline --left-right origin/main...HEAD
   

2. Bei jedem Konflikt die Basis-, Current- und Their-Version der Datei sowie relevante Aufrufer, Tests, Typen, Konfigurationen und aktuelle Commits einsehen. Nicht nur die Konfliktmarkierungen betrachten, auch nicht blind ours oder theirs für die ganze Datei wählen.

3. Absicht beider Seiten beurteilen:

   • origin/main repräsentiert das aktuelle Online-Verhalten; muss beibehalten werden, es sei denn, die aktuelle Funktion ersetzt es explizit.
   • Der aktuelle Branch repräsentiert das aktuelle Funktionsziel; nicht stillschweigend löschen, nur um Konflikte zu beseitigen.
   • Wenn beide Seiten gültige Funktionalitäten hinzufügen, Schnittstellen, Datenflüsse und Randbedingungen integrieren, sodass beide gleichzeitig bestehen können.
   • Testkonflikte gemäß dem endgültigen Produktverhalten aktualisieren; Sperrdateien und generierte Dateien mit den vom Repository vorgeschriebenen Tools neu generieren.

4. Dateien ohne Konfliktmarkierungen bearbeiten, git add ausführen, sicherstellen, dass git diff --name-only --diff-filter=U leer ist.

5. Minimale Validierung in Bezug auf die Konfliktdateien durchführen, dann die vom Repository geforderte vollständige Validierung ausführen.

6. Merge- oder Fix-Commit erstellen, den ursprünglichen Prozess fortsetzen.

Wenn die Absicht allein aus den Konfliktblöcken nicht ersichtlich ist, weiterhin Beweise aus Implementierung, Tests, Aufrufketten, Commit-Historie und Projektdokumentation sammeln. Nur wenn sich zwei Verhaltensweisen gegenseitig ausschließen und die Produktabsicht nicht ableitbar ist, den Benutzer fragen, dabei die Optionen, Auswirkungen und die empfohlene Entscheidung auf einmal klar darlegen.

Schritt 3.5: Lokale Validierung

Basierend auf den aktuellen Änderungen und der Repository-Dokumentation nach vorhandenen Validierungsbefehlen suchen:

1. Zuerst AGENTS.md, CONTRIBUTING.md und README.md lesen.
2. Dann package.json, pyproject.toml, Makefile, CI-Konfiguration und andere Projektdateien prüfen.
3. Bei Bedarf Abhängigkeiten mit dem vorhandenen Paketmanager des Projekts gemäß der Sperrdatei installieren, keine Upgrade eigenmächtig durchführen.
4. Zuerst direkt mit dem Änderungsumfang zusammenhängende Checks ausführen, dann die vom Repository geforderten Lint-, Typecheck-, Test- oder Build-Schritte.
5. Wenn kein vertrauenswürdiger Befehl gefunden wird, dem Benutzer klar mitteilen, welche Validierungen übersprungen wurden und warum; keine Befehle erfinden.

Validierungsfehler-Reparaturzyklus

Bei Validierungsfehlern nicht pausieren, sondern nach folgendem Zyklus vorgehen:

1. Vollständige Fehlerausgabe speichern, die erste Grundursache lokalisieren, nicht nur den letzten Kaskadenfehler beheben.
2. Beurteilen, ob der Fehler aus Produktcode, Testerwartungen, Typen, Formatierung, Abhängigkeiten, Konfiguration oder Umgebung stammt.
3. Die minimal korrekte Reparatur durchführen, die sowohl die Online-Funktionalität als auch die aktuelle Funktionalität erfüllt:
   • Zuerst den vorhandenen Formatter oder Lint-Autofix des Repositorys verwenden, dann verbleibende Probleme bearbeiten.
   • Code-Defekte im Code beheben.
   • Tests nur aktualisieren, wenn die aktuelle Funktion absichtlich das Verhalten ändert und die ursprüngliche Erwartung nicht mehr aktuell ist; keine gültigen Tests schwächen, überspringen oder löschen.
   • Bei fehlenden Abhängigkeiten in der Umgebung die Umgebung gemäß der Projektsperrdatei wiederherstellen; keine irrelevanten Upgrades vornehmen.
4. Zuerst den fehlgeschlagenen Minimalcheck erneut ausführen, dann alle erforderlichen Checks.
5. Wenn neue Fehler auftreten, Diagnose und Reparatur fortsetzen, bis alles bestanden ist.

Fixes, die vor dem ersten Push entstehen, können in den aktuellen Commit aufgenommen werden; Fixes nach dem ersten Push erzeugen einen neuen Commit und werden normal gepusht; kein Force Push, um die Historie zu glätten. Solange jede Runde neue Beweise oder wesentliche Fortschritte bringt, weitermachen, nicht aufgrund häufiger Fehler aufgeben.

Schritt 4: Pushen und PR erstellen

git push -u origin <branch-name>

Bei abgelehntem Push nach Art des Problems klassifizieren:

• Remote-Branch mit demselben Namen enthält nicht zusammenhängende Inhalte: Automatisch einen eindeutigen Branch-Namen wählen und pushen.
• Remote-Branch mit demselben Namen gehört zur gleichen Funktion und enthält neue Commits: Nach dem Fetch den Remote-Branch mergen, Konflikte lösen, validieren und erneut pushen.
• Temporärer Netzwerk- oder GitHub-Fehler: Kurz wiederholen und den Dienststatus prüfen.
• Fehlende Authentifizierung oder Schreibberechtigung: Vollständigen Arbeitszustand erhalten und Benutzer um Autorisierung bitten.

Mit gh pr create den PR erstellen:

• base: main
• head: neuer Branch
• Titel: Commit-Nachricht
• Body: 2–3 Zusammenfassungspunkte, Übersicht der geänderten Dateien, Validierungsergebnisse und 🤖 Finale via git-coda

Wenn der PR bereits existiert, wiederverwenden, nicht doppelt erstellen. Nach erfolgreicher Erstellung dem Benutzer die PR-URL zeigen, dann ohne Warten auf Antwort fortfahren.

Schritt 5: Auf CI warten und reparieren

Mit verfügbaren Repository-Befehlen wie gh pr checks <pr-number> --watch auf erforderliche Checks warten.

Bei fehlgeschlagenen Checks:

1. Mit Befehlen wie gh pr checks, gh run view --log-failed die fehlgeschlagenen Aufgaben und Logs lesen.
2. Wenn lokal reproduzierbar, zuerst reproduzieren und die Grundursache nach dem „Validierungsfehler-Reparaturzyklus“ beheben.
3. Fix committen und normal pushen, erneut auf CI warten.
4. Wiederholen, bis alle erforderlichen Checks bestanden sind.

Wenn Checks lange anhängig sind, Workflow-, Concurrency-Queue und GitHub-Status prüfen; wenn möglich, fehlgeschlagene Aufgaben selbst neu starten. Nur wenn Aufgaben von einer berechtigten Person genehmigt werden müssen oder externe Dienste dauerhaft nicht verfügbar sind, den Benutzer einbeziehen.

Schritt 6: Neuesten main synchronisieren und Squash-Merge

Vor dem Merge den Hauptbranch erneut synchronisieren:

git fetch origin main
git merge --no-edit origin/main

Bei Konflikten nach dem „Konfliktbehandlungsprozess“ lösen, lokale Validierung erneut durchführen, pushen und auf CI warten. Dann direkt mergen:

gh pr merge <pr-number> --squash --delete-branch

Wenn beim Merge eine Basis-Aktualisierung oder Konflikte gemeldet werden, den Zyklus aus Synchronisieren, Lösen, Validieren, Pushen und Warten auf CI erneut durchführen und erneut mergen. Wenn das Repository eine Merge-Queue unterstützt, in der Queue warten, bis der PR tatsächlich gemergt ist.

Branch-Schutz nicht umgehen. Bei fehlenden erforderlichen Genehmigungen, Signaturen oder Berechtigungen handelt es sich um eine externe Blockade: Die genaue Rückmeldung von GitHub anzeigen, die bereits abgeschlossenen Schritte und die Aktion, die der Benutzer ausführen muss, erläutern.

Schritt 7: Zu main zurückkehren und Ergebnis bestätigen

git checkout main
git pull --ff-only origin main
git status --short --branch
gh pr view <pr-number> --json state,mergedAt,mergeCommit,url

Sicherstellen, dass der PR-Status „merged“ ist, und den endgültigen main-Commit-Hash ausgeben. Wenn lokales main vorab existierende exklusive Commits hat und nicht fast-forward kann, diese behalten, keine destruktiven Maßnahmen ergreifen; dennoch bestätigen, dass der Remote-PR gemergt wurde, und den lokalen Zustand klar darlegen.

Endgültigen Status ausgeben:

🚀 Ship abgeschlossen!
  ✓ Branch <branch-name> in main gemergt
  ✓ Lokale Validierung und erforderliche CI bestanden
  ✓ Aktuell auf main mit neuestem Code (<commit-hash>)
  ✓ PR: <pr-url>

Fehlerbehandlungsprinzipien

• Vor jedem Schritt kurz erklären, was gerade getan wird.
• Nach einem Befehlsfehler zuerst diagnostizieren, reparieren und wiederholen, mit dem Ziel des erfolgreichen Merges.
• Kein Force Push, reset --hard oder andere destruktive Wiederherstellungsmethoden verwenden.
• Konflikte aktiv lösen, dabei sowohl die aktuellen Online-Funktionen als auch die Funktionsziele schützen.
• Test-, Lint-, Typprüfungs-, Build-, Commit-Hook- und CI-Fehler aktiv beheben.
• Keine Bestätigungen für automatisch abgeleitete Branch-Namen, Commit-Nachrichten, PR-Titel, PR-Body oder die Fortsetzung einholen.
• Reparierbare Fehler, mehrfache Debug-Runden oder zeitaufwändige Prozessschritte nicht als Blockade betrachten.
• Nur bei externen Bedingungen, die die aktuelle Umgebung tatsächlich nicht lösen kann, pausieren; dabei einen fortsetzbaren Zustand mit Branch, Commit und Logs hinterlassen.
• Bei Pause nur eine klare, minimale, ausführbare Benutzeraktion angeben; nach deren Abschluss kann der Prozess an der gleichen Stelle fortgesetzt werden.

Häufige Grenzfälle

Situation	Behandlung
Aktuell auf einem Nicht-main-Branch mit Arbeitsbereichsänderungen	Stash → Branch basierend auf origin/main erstellen → apply → Konflikte lösen
Aktueller Branch hat bereits unveröffentlichte Commits	Commits behalten, neuestes origin/main mergen, dann fortfahren
Keine uncommitteten Änderungen	Prüfen, ob unveröffentlichte Commits relativ zu origin/main vorliegen; nur wenn beides fehlt, anhalten
Branch-Name existiert bereits	Automatisch eindeutigen Suffix generieren; bei gleichnamigem Remote-Branch derselben Funktion wiederverwenden und integrieren
Konflikt bei stash apply oder Merge	Funktionsabsicht beider Seiten analysieren, Implementierung integrieren, validieren und fortfahren
Fehlschlag von Lint/Test/Typecheck/Build	Grundursache beheben und zyklisch validieren, Fehler nicht an Benutzer übergeben
CI-Fehler	Logs lesen, lokal reproduzieren, reparieren, pushen, auf nächste CI-Runde warten
main wird vor Merge aktualisiert	Neuestes origin/main mergen, Konflikte lösen, Validierungszyklus erneut durchlaufen
gh nicht angemeldet	Aufforderung: gh auth login ausführen
Erforderliche manuelle Freigabe oder keine Schreibberechtigung	Zustand erhalten, nur die erforderliche externe Aktion für den Benutzer erläutern
Benutzer gibt --no-squash an	--merge verwenden