Ein Design-Dokument (RFC) schreiben, über das Reviewer entscheiden können

Ziel

Eine grössere Änderung von den Personen entscheiden lassen, die mit ihr leben müssen – auf Grundlage eines Dokuments, das sich in zwanzig Minuten lesen lässt, und bevor jemand den Code schreibt. Später dient dasselbe Dokument als Aufzeichnung, warum das System so aussieht, wie es aussieht.

Voraussetzungen

Eine Änderung, die für eine Pull-Request-Beschreibung zu gross oder zu umstritten ist; bekannte Reviewer mit der Befugnis, anzunehmen; ein Ort neben dem Code (ein Verzeichnis docs/rfcs/, eine nummerierte Datei, ein Pull Request). PEP 1 und die RFC-Vorlage von Rust sind öffentliche Beispiele solcher Prozesse. Das Dokumentationskapitel von «Software Engineering at Google» hält fest, dass die dortigen Vorlagen verlangen, Sicherheit, Internationalisierung, Speicherbedarf und Datenschutz zu bedenken, und dass diese Teile meist von Fachleuten des jeweiligen Gebiets geprüft werden.

Schritte

1. Das Problem vor jedem Vorschlag beschreiben: Wer ist betroffen, was passiert heute, welche Randbedingung erzwingt eine Änderung. Lässt sich das Problem nicht in einem Absatz sagen, ist das Dokument nicht reif.
2. Ziele als nummerierte, prüfbare Aussagen aufführen, dazu Nicht-Ziele, die den Umfang eingrenzen. Nicht-Ziele verhindern, dass das Review in benachbarte Wünsche ausufert.
3. Den Vorschlag zweimal erklären, wie es die Rust-Vorlage vorsieht: einmal auf Anwenderebene (wie sieht die Änderung für Nutzende aus), einmal auf Referenzebene mit genauer Semantik, Formaten und Randfällen.
4. Die erwogenen Alternativen festhalten und warum jede verworfen wurde. PEP 1 sieht einen Abschnitt zu verworfenen Ideen samt Begründung vor, damit dieselbe Idee nicht erneut aufgebracht wird; die Rust-Vorlage hat dafür «Rationale and alternatives».
5. Nachteile, Kompatibilitätsfolgen, Migration und Rollout sowie Betriebskosten ehrlich benennen; ein Dokument ohne Nachteile liest sich wie Werbung.
6. Mit offenen Fragen schliessen, getrennt in «muss in diesem Review entschieden werden» und «kann während der Umsetzung geklärt werden».
7. Mit Frist zur Durchsicht verteilen, Kommentare im Dokument statt im Chat beantworten und den Ausgang in einer Statuszeile festhalten (Entwurf, angenommen, abgelehnt, abgelöst). Abgelehnte Dokumente aufbewahren: Sie antworten der nächsten Person mit derselben Idee.

Erwartetes Ergebnis

Reviewer streiten über das Problem und die Abwägungen, nicht über fehlenden Kontext; das angenommene Dokument wird zur Referenz für die Umsetzung und – wie das zitierte Google-Kapitel nahelegt – beim Start zum Massstab, ob die gesetzten Ziele erreicht wurden.

Grenzen und Prüfbasis

Ein Design-Dokument ist keine Spezifikation; Details ändern sich in der Umsetzung, und das Dokument sollte sagen, welche Teile verbindlich sind. Für kleine Änderungen kostet das Ritual mehr, als es bringt. Die Struktur folgt den zitierten Vorlagen; eine Wirkung auf die Entscheidungsqualität ist hier nicht gemessen.