SamiKhan43/commit-and-pr-writer

Commit und PR-Schreiber

Verwandle eine Reihe von Änderungen in eine klare Commit-Nachricht und eine Pull-Request-Beschreibung, mit der ein Reviewer arbeiten kann. Der Wert liegt darin, warum die Änderung existiert und was schiefgehen könnte, nicht in einer Wiederholung des Diffs.

Sicherheitsregeln (zuerst lesen)

• Führe kein Commit, Push oder PR durch, es sei denn, der Benutzer bittet ausdrücklich darum. Schlage die Befehle vor und lass den Benutzer sie ausführen. Commits und Pushes sind für andere sichtbar und schwer rückgängig zu machen.
• Schreibe niemals geheime Werte in eine Nachricht oder PR. Wenn der Scan ein mögliches Secret erkennt, stoppe und teile dem Benutzer dies mit, bevor du etwas schreibst: Das Secret muss rotiert werden, und es reicht nicht, es aus dem nächsten Commit zu entfernen.
• Erfinde keine Fakten. Keine Issue-Nummern, Testergebnisse, Benchmark-Zahlen oder Motivationen, die du nicht gesehen hast. Wenn der Grund für die Änderung unklar ist, stelle eine kurze Frage oder nenne deine Annahme.

Arbeitsablauf

1. Änderungen sammeln

Wenn du Befehle im Repository des Benutzers ausführen kannst, verwende zuerst den enthaltenen Scanner und lies dann den echten Diff:

python scripts/scan_diff.py                  # gestagte Änderungen (fallback zu ungestagten)
python scripts/scan_diff.py main...HEAD      # gesamter Branch, für einen PR
git diff --staged                            # lies den eigentlichen Diff (verwende --stat zuerst, wenn er groß ist)
git log --oneline main..HEAD                 # bereits vorhandene Commits auf dem Branch, für einen PR

scripts/scan_diff.py gruppiert Dateien nach Bereichen (Code, Tests, Migrationen, Abhängigkeiten, Konfiguration, CI, Dokumentation) und markiert mögliche Secrets, Debug-Überreste, fehlende Tests, Migrationen, sicherheitskritische Pfade, mögliche API-Änderungen und übermäßig große Änderungen. Es ist eine Heuristik, bestätige daher jede Markierung anhand des Diffs.

Wenn du keine Befehle ausführen kannst, bitte den Benutzer, git diff --staged (oder git diff main...HEAD für einen PR) und gegebenenfalls den Issue- oder Tickettext einzufügen. Du kannst eingefügten Text weiterhin mit python scripts/scan_diff.py - an den Scanner übergeben, wenn Codeausführung verfügbar ist.

2. Absicht verstehen

Finde heraus, welches Verhalten sich geändert hat und warum. Hinweise, in dieser Reihenfolge: Branchname und Ticket-ID, bereits auf dem Branch vorhandene Commit-Nachrichten, neue oder geänderte Tests, Kommentare in der Nähe der Änderung, dann die Worte des Benutzers. Siehe Abschnitt 4 in references/guidelines.md.

3. Umfang prüfen

Wenn der Diff unzusammenhängende Aspekte vermischt (ein Feature plus ein Refactoring plus Formatierung, oder unabhängige Module), schlage eine Aufteilung vor, anstatt eine vage Nachricht zu schreiben: Liste die Gruppen, welche Dateien zu jeder gehören und eine Nachricht pro Gruppe, sowie die git add -p-Schritte. Behalte eine logische Änderung pro Commit bei. Handelt es sich bereits um eine logische Änderung, schreibe einen Commit.

4. Commit-Nachricht schreiben

Format: typ(bereich): betreff, dann optional ein Body, dann optionale Fußzeilen.

• Typen: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.
• Betreff: Imperativ ("add", "fix"), Kleinbuchstaben, kein Punkt am Ende, etwa 50 Zeichen und niemals über 72. Beschreibe die Verhaltensänderung, nicht die Dateien.
• Body: Nur, wenn der Grund nicht offensichtlich ist. Leerzeile nach dem Betreff, erkläre warum, umbreche bei etwa 72 Zeichen.
• Fußzeilen: Closes #123 (nur für Nummern, die du kennst) und BREAKING CHANGE: ... wenn Clients oder Deployments brechen. Ein ! nach dem Typ oder Bereich markiert ebenfalls eine Breaking Change.

Überprüfe sie dann. Speichere die Nachricht in einer temporären Datei und führe aus:

python scripts/lint_commit_message.py message.txt

Behebe jeden Fehler und sinnvolle Warnungen, bevor du sie dem Benutzer zeigst.

5. PR-Beschreibung schreiben (wenn nach einem PR gefragt)

Beginne mit assets/pr-template.md. Fülle Was, Warum, Wie testen aus, behalte dann nur die zutreffenden Backend-Auswirkungen-Zeilen (Datenbank und Migrationen, API-Änderungen, Sicherheit und Autorisierung, Performance, Konfiguration und Flags, Rollout und Rollback) und lösche den Rest. Regeln:

• Titel: Gleiches Format wie ein Commit-Header, da er bei Squash-Merge zum Commit auf main wird.
• Wie testen: Exakte Befehle, die du aus dem Repository rechtfertigen kannst (z. B. die Testdatei, die du geändert gesehen hast). Sage "Tests nicht ausgeführt", anstatt zu implizieren, sie wären bestanden.
• Breaking Changes: Sage, wer betroffen ist, was sie tun müssen und den Zeitplan.
• Migrationen: Sage, ob alter Code während des Deployments noch funktioniert und wie man zurückrollt.
• Bleibe angemessen. Ein einzeiliger Fix braucht eine zweizeilige PR, nicht die gesamte Vorlage.

6. Ergebnis präsentieren

Antworte in dieser Reihenfolge:

1. Wichtiger Hinweis (nur, wenn der Scan etwas Reales gefunden hat): Secrets, Debug-Code, fehlende Tests, ein sehr großer Diff, eine riskante Migration.
2. Die Commit-Nachricht in einem Codeblock (oder der Aufteilungsplan mit einer Nachricht pro Commit).
3. Der PR-Titel und die Beschreibung in einem Markdown-Codeblock, bereit zum Einfügen. Verwende vier Backticks darum, wenn der Body Codeblöcke enthält.
4. Optionale Befehle, die der Benutzer ausführen kann, z. B. git commit -F message.txt oder gh pr create --title "..." --body-file pr.md. Präsentiere sie als Vorschläge.

Halte die Antwort kurz. Wiederhole nicht den Diff.

Ausgabe an die Änderung anpassen

• Tippfehler, Doku oder Konfig-Änderung: einzeiliger Commit, kein Body, zweizeilige PR.
• Normale Änderung: Header plus kurzer Body, eine PR mit Was / Warum / Wie testen.
• Große oder riskante Änderung (Migration, Auth, öffentliche API): vollständige PR mit den relevanten Backend-Auswirkungsabschnitten; schlage Aufteilung vor, wenn der Scan sie als groß markiert.

Beispiel

Eingabezusammenfassung: Gestagter Diff ändert app/auth.py, um exp, iss, aud beim Dekodieren von Tokens zu validieren, fügt tests/test_auth.py::test_expired_token hinzu, Branch fix/42-expired-tokens.

Ausgabe:

fix(auth): lehne abgelaufene Refresh-Token ab

Token wurden nach Ablauf akzeptiert, weil exp dekodiert, aber nie
validiert wurde. Validiere exp, iss und aud bei jedem Dekodieren und gib 401 zurück.

Closes #42

Der PR-Titel wäre fix(auth): lehne abgelaufene Refresh-Token ab, mit einem Warum, das den Fehler benennt, Wie testen, das auf pytest tests/test_auth.py::test_expired_token verweist, und einer Sicherheit / Autorisierung-Zeile, die besagt, dass zuvor gültige abgelaufene Token jetzt einen 401 erhalten.

Gebündelte Dateien

• scripts/scan_diff.py: Fasst einen Diff zusammen und markiert Risiken. Verwendung: python scripts/scan_diff.py [git-diff-args | -]. Exit-Code 1 bedeutet, ein mögliches Secret wurde gefunden.
• scripts/lint_commit_message.py: Prüft eine Nachricht auf das Conventional-Commit-Format. Verwendung: python scripts/lint_commit_message.py message.txt (oder - für stdin). Exit-Code 1 bedeutet Fehler.
• assets/pr-template.md: Das PR-Beschreibungsgerüst zum Ausfüllen. Es kann auch nach .github/pull_request_template.md kopiert werden, wenn der Benutzer eine Standardvorlage in seinem Repository haben möchte.
• references/guidelines.md: Commit-Typen mit Beispielen, gute und schlechte Nachrichten, Breaking Changes, wie man Diffs aufteilt, PR-Größen, Backend-PR-Abschnitte, Issue-Linking-Schlüsselwörter und was man nicht schreiben sollte. Lies es, wenn ein Fall oben nicht abgedeckt ist.