Comparer le document OpenAPI en intégration continue détecte des changements cassants que la revue de code manque

Hypothèse

Les changements cassants d'une API HTTP sont souvent invisibles dans le diff de code que lit un relecteur : un champ de structure renommé, un validateur rendu plus strict, un sérialiseur qui cesse d'émettre une propriété. Ils sont en revanche visibles dans la description d'API générée. La spécification OpenAPI (citée) décrit ce document comme permettant aux humains comme aux machines de comprendre les capacités d'un service sans accès au code source ; un outil tel qu'oasdiff (cité comme outil en ligne de commande pour comparer et détecter les changements cassants dans des spécifications OpenAPI) classe les différences entre deux documents comme cassantes ou non. L'AIP-180 de Google sur la compatibilité ascendante (cité) énumère les changements qui comptent comme cassants, tels que la suppression ou le renommage de champs et le changement de types. L'hypothèse est que conditionner les fusions à un tel diff détecte une classe de régressions que la seule revue de l'implémentation ne détecte pas, avec un taux de faux positifs tolérable une fois exclues les parties volatiles du document.

Prédiction

Les dépôts qui ajoutent ce contrôle enregistreront, par trimestre, moins de changements cassants découverts après la publication (rapports de bugs client, retours en arrière, correctifs de compatibilité d'urgence) que lors des trimestres précédents, et le journal du contrôle contiendra des changements cassants bloqués que la pull request correspondante ne mentionnait pas. Le nombre de changements cassants intentionnels ne baissera pas ; ils seront en revanche étiquetés et acheminés via le processus de gestion des versions.

Test proposé

1. Choisir des services dont le document OpenAPI est généré à partir du code, de sorte qu'il reflète l'implémentation, et qui disposent d'au moins deux trimestres d'historique de publication.
2. Reconstituer à partir de l'historique git le document à chaque publication, exécuter le diff de manière rétrospective, et rapprocher les changements classés comme cassants des incidents post-publication connus.
3. Activer le contrôle ; pour chaque changement bloqué, consigner si l'auteur l'avait voulu, si la revue l'avait remarqué, et comment il a été résolu.
4. Comparer les incidents de changement cassant post-publication par publication, avant et après ; rapporter les faux positifs (signalés mais inoffensifs) dans un décompte distinct.

Statut

Aucun résultat n'est revendiqué. Le contrôle ne peut pas voir les changements comportementaux que le document n'exprime pas (signification d'une valeur, ordre, timing), et ses règles de classification peuvent différer de ce qu'une base de clients particulière tolère.