Was macht PR-Erklärer?
Erstelle ein Dokument, das einem Teamkollegen eine Änderung erklärt: Was falsch war oder fehlte, wie das System darum herum funktioniert, was die Änderung bewirkt und wie wir wissen, dass es funktioniert.
Argumente
- Ziel: eine PR-Nummer oder URL oder nichts.
- Mit einer PR und verfügbarer
gh-CLI: Details mitgh pr view <url> --json title,url,body,baseRefName,headRefName,headRefOid,filesund den Diff mitgh pr diff <url>abrufen. Umgebenden Code am Head-Commit der PR lesen (git show <headRefOid>:<path>), nicht lokalesHEAD. - Ohne PR oder ohne
gh: lokale Änderung erklären.git diff <base>...HEADfür Commits undgit diffplusgit statusfür nicht committete Arbeit verwenden, wobei<base>der Standard-Branch oder der erste Commit ist.
- Mit einer PR und verfügbarer
--local: auch bei vorhandener PR den lokalen Checkout verwenden (nicht gepushte Arbeit). Auf der Seite vermerken, dass sie lokale Änderungen widerspiegelt.--concise: eine kurze Version, die in etwa zwei Minuten lesbar ist. Höchstens eine Grafik, höchstens 3 Schnipsel, kein Inhaltsverzeichnis, 1–3 Sätze pro Abschnitt.--md: Markdown statt HTML ausgeben (Standard-DateiHANDOVER.mdim Repository-Root, es sei denn, der Benutzer gibt einen Namen an). Für Übergaben und wenn kein Browser zur Hand ist.
Zielgruppe und Ton
- Der Leser ist ein Junior-Entwickler im Team. Kurze Sätze, einfache Verben, eine Idee pro Absatz verwenden.
- Grundlagen nicht definieren (REST, SQL, JWT, React-Hooks) und keine nicht-technischen Analogien verwenden. Technisch bleiben, mit echten Modul-, Funktions-, Routen- und Feldnamen sowie echten Zahlen.
- Die Formulierung einfach halten, nicht den Inhalt. Ungewöhnliche Bibliotheksaufrufe oder Muster beim ersten Auftreten erklären.
- Als Endfassung schreiben. Den aktuellen Zustand direkt beschreiben. Kein Changelog oder „früher dachten wir“-Formulierung.
- Ehrlich bezüglich der Sicherheit sein. Unbewiesene Behauptungen mit „wahrscheinlich, noch nicht bestätigt“ kennzeichnen.
Umfang: die Änderung erklären, nicht den Diff
- Die Dateien auswählen, die die Geschichte erzählen, und darin nur die relevanten Zeilen.
- 1–3 Schnipsel pro Datei verwenden, jeder unter ~25 Zeilen, mit
...für ausgelassene Teile. Jeden mit Dateipfad und 2–4 Sätzen versehen, was er tut und warum. - Bei einem Fix den Code zeigen, der den Bug verursacht hat, sowie den Diff des Fixes.
- Code nach Runtime-Ablauf ordnen, nicht nach Diff-Reihenfolge.
- Plumbing, Umbenennungen und Formatierung überspringen. In einem Satz erwähnen, wenn ein Reviewer sie im Diff sehen wird.
1. Die Änderung verstehen
- Den Diff und den umgebenden Code lesen. Den Modus festlegen:
- Feature: neues Verhalten oder große Umstrukturierung.
- Bug-Fix: ein Symptom, eine Ursache und eine Lösung.
- Den letzten Verifikationslauf finden: Testbefehl und -anzahlen, und idealerweise den Nachweis, dass ein neuer Regressionstest ohne den Fix fehlschlägt und mit ihm besteht. Wenn dieser Nachweis nicht existiert und es günstig ist, ihn erstellen:
git stash push -- <src files>, den Test ausführen, danngit stash pop. Auch nach einem manuellen oder End-to-End-Check suchen (CLI-Ausgabe, eine Anfrage, ein Screenshot). Nur den letzten Lauf von jedem zeigen. - Erkenntnisse aus der Konversation nutzen (Ursachenanalyse, QA-Bericht, Ticket), wo vorhanden.
2. Gerüst
Jedes Dokument beginnt mit einer Augenbrauenzeile (repo · PR #n · ticket oder repo · lokale Änderungen), einem Titel in einfacher Sprache und einer Einleitung von 1–2 Sätzen.
Bug-Fix
- Was schiefgelaufen ist: das Symptom, wo es gesehen wurde, was ausgeschlossen wurde.
- Ursache: die genaue Stelle, an der die Daten oder der Ablauf brechen (
datei:zeile), mit einer Grafik, falls hilfreich. - Der Code, der es verursacht hat: ein oder zwei Schnipsel.
- Der Fix: ein Diff-Schnipsel und warum er funktioniert. Nebeneffekte nennen, die er ebenfalls behebt.
- Wie wir es wissen: ein Regressionstest, der vorher fehlschlägt und nachher besteht, Gesamtsuite-Anzahlen, ein manueller Check.
- Erkenntnisse: 2–4 Lektionen, die ein Junior anderswo wiederverwenden kann.
Feature
- Warum: das Problem oder Ziel, mit Belegen.
- Wo es sitzt: Architektur- oder Modulkontext (Diagramm), plus was absichtlich unverändert ist.
- Wie es abläuft: Schritte oder ein Ablaufdiagramm, verknüpft mit den Code-Karten.
- Code-Walkthrough: eine Karte pro wichtiger Datei, in Ablaufreihenfolge.
- Verhalten, das man kennen sollte: Randfälle, Zustände, Fehlermodi (eine Tabelle, wenn mehr als 3).
- Verifikation: nur den letzten Lauf.
- Erkenntnis für Reviewer: das mentale Modell in 2–3 Zeilen und wo im Diff am genauesten hingeschaut werden sollte.
Übergabe-Ergänzungen (immer mit --md einfügen; in HTML optional):
- Wie ausführen / testen: genaue Befehle.
- Getroffene Annahmen: Entscheidungen, wo die Spezifikation still war, und warum.
- Offene Fragen für das Business: geordnet nach Auswirkung.
- Risiken und Rollback: was in Produktion schiefgehen könnte und wie zurückgesetzt wird.
- Nächste Schritte: was du mit mehr Zeit tun würdest.
Kurzfassung: nur Was schiefgelaufen ist / Was und warum, Ursache / Wie es funktioniert, Der Fix / Wichtiger Code und Wie wir es wissen.
3. Grafiken: nur, wenn sie etwas erklären, was der Text nicht kann
| Inhalt | Verwendung |
|---|---|
| Modul- oder Dienstarchitektur, wer wen aufruft, Anfragesequenz | Mermaid flowchart / sequenceDiagram (≤ ~12 Knoten) |
| Ein Zweig, der sich vorher und nachher anders verhält | Vorher/Nachher-Tabelle oder ein kleines statisches SVG |
| Daten, die durch Stufen gehen, von einem Filter verworfene Werte | Eine Tabelle mit Beispiel-Eingaben → Ausgaben, vorher vs. nachher |
| Zustände, Befehle, Risiken, Verträge | Tabellen |
In Markdown umfasste ```mermaid-Blöcke verwenden (GitHub rendert sie). Animationen nur hinzufügen, wenn der Benutzer darum bittet.
4. Erstellung
- HTML: von
references/page-template.htmlausgehen (in sich geschlossen, helles und dunkles Design, Mermaid und highlight.js von einem CDN). Speichern unter.pr-review/<name>.html, benannt nach dem Ticket oder der PR, oderlocal-<kurzbeschreibung>. Aus Git ausschließen: wenngit check-ignore -q .pr-review/fehlschlägt,.pr-review/an.git/info/excludeanhängen..gitignorenur auf Anfrage bearbeiten.- Code-Schnipsel:
<pre><code class="language-<sprache>">…</code></pre>, HTML-escaped. Für einen Fix-Difflanguage-diffmit-/+-Zeilen verwenden. - Mermaid:
<pre class="mermaid">…</pre>. Niemals Farben fest codieren.
- Code-Schnipsel:
- Markdown (
--md): einfaches GitHub-Flavored Markdown, gleiches Gerüst, kein HTML.
5. Einmal prüfen
- HTML: wenn ein Browser-Werkzeug verfügbar ist, die Seite einmal in Desktop-Breite und einmal bei ~400px öffnen. Prüfen, ob Mermaid rendert und Code hervorgehoben ist, in einem Durchgang beheben, nicht wiederholen. Sonst sagen, dass es nicht in der Vorschau war, und den Befehl zum Öffnen angeben (
openauf macOS,startauf Windows,xdg-openauf Linux). - Jedes
datei:zeile, jede Zahl und jeden Befehl auf der Seite erneut mit dem Code abgleichen. Fakten müssen exakt sein.
6. Rückmeldung
Antworten mit:
- dem Dateipfad
- dem Modus und den abgedeckten Abschnitten
- den verwendeten Grafiken und was jede erklärt
- welchem Verifikationslauf das Dokument zeigt
- allem, was als „noch nicht bestätigt“ markiert ist
Niemals einen PR-Text bearbeiten, einen Kommentar posten oder etwas pushen, ohne vorher zu fragen.