Ein Designdokument oder RFC schreiben, über das Reviewende entscheiden können

Ziel

Eine wesentliche Änderung von den Personen entscheiden lassen, die damit leben müssen, auf Basis eines Dokuments, das sie in zwanzig Minuten lesen können, bevor jemand den Code schreibt. Das Dokument dient später als Aufzeichnung dafür, warum das System so aussieht, wie es aussieht.

Voraussetzungen

Eine Änderung, die für eine Pull-Request-Beschreibung zu gross oder zu umstritten ist; ein bekannter Kreis von Reviewenden mit der Befugnis zur Annahme; ein Ort, an dem das Dokument neben dem Code liegt (ein Verzeichnis docs/rfcs/, eine nummerierte Datei, ein Pull Request). PEP 1 (zitiert) und die Rust-RFC-Vorlage (zitiert) sind öffentliche Beispiele solcher Vorgehen; Googles Designdokument-Vorlagen (zitiert) verlangen von der Autorenschaft, Sicherheit, Internationalisierung, Speicherung und Datenschutz zu berücksichtigen, wobei diese Teile meist von Fachleuten geprüft werden.

Schritte

1. Die Problembeschreibung vor jedem Vorschlag schreiben: wer betroffen ist, was heute geschieht, welcher Zwang eine Änderung erfordert. Lässt sich das Problem nicht in einem Absatz formulieren, ist das Dokument nicht bereit.
2. Ziele als nummerierte, prüfbare Aussagen auflisten, sowie Nicht-Ziele, die den Umfang eingrenzen. Nicht-Ziele verhindern, dass sich der Review auf angrenzende Wünsche ausweitet.
3. Den Vorschlag zweimal erklären, wie es die Rust-Vorlage tut: eine Erklärung auf Leitfaden-Ebene, wie die Änderung sich für Nutzende darstellt, dann eine Erklärung auf Referenz-Ebene mit präziser Semantik, Formaten und Grenzfällen.
4. Die erwogenen Alternativen und die Gründe für ihre Ablehnung festhalten. PEP 1 verlangt abgelehnte Ideen samt Begründung, damit die Diskussion nicht wiederholt wird; die Rust-Vorlage hat zu demselben Zweck einen Abschnitt zu Begründung und Alternativen.
5. Nachteile, Kompatibilitätsauswirkungen, Migration und Rollout sowie den betrieblichen Aufwand ehrlich darlegen; ein Dokument ohne Nachteile liest sich wie Werbung.
6. Mit offenen Fragen enden, unterteilt in „muss in diesem Review entschieden werden“ und „kann während der Umsetzung geklärt werden“.
7. Mit einer Review-Frist verteilen, Kommentare im Dokument statt im Chat beantworten und das Ergebnis in einer Statuszeile festhalten (Entwurf, angenommen, abgelehnt, ersetzt). Abgelehnte Dokumente aufbewahren; sie beantworten der nächsten Person dieselbe Idee.

Erwartetes Ergebnis

Reviewende 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, zu einem Massstab beim Launch dafür, ob die genannten Ziele erreicht wurden.

Grenzen und Prüfbasis

Ein Designdokument ist keine Spezifikation; Details ändern sich während der Umsetzung, und das Dokument sollte sagen, welche Teile verbindlich sind. Für kleine Änderungen kostet der Aufwand mehr, als er einspart. Die Struktur folgt den zitierten Vorlagen; eine Wirkung auf die Entscheidungsqualität wird hier nicht gemessen.