Comparar (diff) el documento OpenAPI en la integración continua detecta cambios incompatibles que la revisión de código pasa por alto

Hipótesis

Los cambios incompatibles en una API HTTP suelen ser invisibles en el diff de código que revisa una persona: un campo de estructura renombrado, un validador vuelto más estricto, un serializador que deja de emitir una propiedad. Sí son visibles en la descripción generada de la API. La especificación OpenAPI (citada) describe el documento como aquel que permite a personas y a sistemas comprender las capacidades de un servicio sin acceso al código fuente; una herramienta como oasdiff (citada como una herramienta de línea de comandos para comparar y detectar cambios incompatibles en especificaciones OpenAPI) clasifica las diferencias entre dos documentos como incompatibles o no. La AIP-180 de Google sobre compatibilidad hacia atrás (citada) enumera qué cambios cuentan como incompatibles, tales como eliminar o renombrar campos y cambiar tipos. La hipótesis es que condicionar las fusiones (merges) a ese diff detecta una clase de regresiones que la sola revisión de la implementación no detecta, con una tasa de falsos positivos tolerable una vez excluidas las partes volátiles del documento.

Predicción

Los repositorios que añadan esta condición registrarán, por trimestre, menos cambios incompatibles descubiertos después de la publicación (reportes de errores de clientes, reversiones, parches de compatibilidad de emergencia) que en los trimestres anteriores, y el registro de la condición contendrá cambios incompatibles bloqueados que el pull request correspondiente no mencionaba. El número de cambios incompatibles intencionados no bajará; en cambio, se etiquetarán y se encauzarán a través del proceso de versionado.

Prueba propuesta

1. Elegir servicios que generen su documento OpenAPI a partir del código, de modo que el documento refleje la implementación, y que cuenten con al menos dos trimestres de historial de versiones.
2. Reconstruir a partir del historial de git el documento en cada versión, ejecutar el diff de forma retrospectiva, y emparejar los cambios clasificados como incompatibles con incidentes conocidos posteriores a la publicación.
3. Activar la condición; para cada cambio bloqueado, registrar si la persona autora lo había previsto, si la revisión lo había detectado, y cómo se resolvió.
4. Comparar los incidentes de cambios incompatibles posteriores a la publicación por versión, antes y después; reportar los falsos positivos (señalados pero inofensivos) como un recuento aparte.

Estado

No se afirma ningún resultado. La condición no puede detectar cambios de comportamiento que el documento no expresa (el significado de un valor, el orden, la temporización), y sus reglas de clasificación pueden diferir de lo que tolera una base de clientes concreta.