Das Vergleichen des OpenAPI-Dokuments in der CI erkennt Breaking Changes, die im Code-Review übersehen werden

Hypothese

Breaking Changes an einer HTTP-API sind im Code-Diff, das eine Reviewerin oder ein Reviewer liest, oft unsichtbar: ein umbenanntes Struct-Feld, ein strenger gemachter Validator, ein Serialisierer, der eine Eigenschaft nicht mehr ausgibt. Sichtbar sind sie in der generierten API-Beschreibung. Die OpenAPI-Spezifikation (zitiert) beschreibt das Dokument als etwas, das Menschen und Computern erlaubt, die Fähigkeiten eines Dienstes ohne Zugriff auf den Quellcode zu verstehen; ein Werkzeug wie oasdiff (zitiert als Kommandozeilenwerkzeug zum Vergleichen und Erkennen von Breaking Changes in OpenAPI-Spezifikationen) klassifiziert die Unterschiede zwischen zwei Dokumenten als brechend oder nicht. Googles AIP-180 zur Abwärtskompatibilität (zitiert) listet auf, welche Änderungen als brechend gelten, etwa das Entfernen oder Umbenennen von Feldern und das Ändern von Typen. Die Hypothese lautet, dass das Blockieren von Merges anhand eines solchen Diffs eine Klasse von Regressionen erkennt, die das Review der Implementierung allein nicht erkennt, bei einer tolerierbaren Falsch-positiv-Rate, sobald volatile Teile des Dokuments ausgeschlossen werden.

Vorhersage

Repositories, die die Schranke einführen, werden pro Quartal weniger nach dem Release entdeckte Breaking Changes verzeichnen (Bugmeldungen von Clients, Rollbacks, dringende Kompatibilitäts-Patches) als in den Quartalen davor, und das Log der Schranke wird blockierte Breaking Changes enthalten, die der zugehörige Pull Request nicht erwähnte. Die Zahl beabsichtigter Breaking Changes wird nicht sinken; sie werden stattdessen gekennzeichnet und über den Versionierungsprozess geleitet.

Vorgeschlagener Test

1. Dienste auswählen, die ihr OpenAPI-Dokument aus dem Code generieren, sodass das Dokument die Implementierung widerspiegelt, und die mindestens zwei Quartale Release-Historie aufweisen.
2. Das Dokument zu jedem Release aus der Git-Historie rekonstruieren, den Diff rückblickend ausführen und als brechend klassifizierte Änderungen mit bekannten Vorfällen nach dem Release abgleichen.
3. Die Schranke einschalten; für jede blockierte Änderung festhalten, ob die Autorin oder der Autor sie beabsichtigt hatte, ob das Review sie bemerkt hatte, und wie sie gelöst wurde.
4. Nach-Release-Vorfälle mit Breaking Changes pro Release vorher und nachher vergleichen; Falsch-positive (markiert, aber harmlos) als separate Zahl berichten.

Status

Es wird kein Ergebnis behauptet. Die Schranke kann Verhaltensänderungen nicht erkennen, die das Dokument nicht ausdrückt (Bedeutung eines Werts, Reihenfolge, Timing), und ihre Klassifikationsregeln können von dem abweichen, was eine bestimmte Client-Basis toleriert.