La vida de un breaking change
Un null entra en una base de código escondido en un PR de 380 líneas. Síguelo: detéctalo en revisión, entiende a quién rompe, blíndalo con tests y documéntalo antes de que atrape al siguiente.
Casi ningún cambio que rompe llega anunciado. Llega dentro de un PR que arregla algo real, escrito por alguien con buenas intenciones, en una línea que no parece importante.
En atlas/gateway esa línea cambió Promise<Response> por
Promise<Response | null>. El fix del timeout era correcto: una petición a un
upstream lento ya no se queda colgada para siempre. El tipo de retorno se coló
de acompañante.
Esta ruta sigue ese null de principio a fin. Lo detectas en un diff que
preferirías aprobar sin leer, decides a quién rompe de verdad, lo fijas con
tests para que no pueda desaparecer en silencio, y lo documentas para que el
siguiente no caiga en la trampa.
Son cuatro trabajos distintos sobre el mismo defecto, y solo el primero se
parece a lo que la gente llama "revisar código". Los otros tres son los que
deciden si ese null es una decisión o un accidente que nadie recuerda haber
tomado.
Parte 1 de 3
Detectarlo
El PR #214 arregla un timeout real y trae ruido de sobra: un console.log olvidado, limpieza que no venía a cuento y un tipo de retorno cambiado. Primero por qué los PRs ruidosos acaban aprobados de trámite; después te toca revisarlo a ti.
Cultura de revisión
Revisión de código que no paraliza PRs: límites de tamaño, etiquetas Conventional Comments y cuándo solicitar cambios frente a aprobar con comentarios.
Revisa un pull request ruidoso
Un PR de 380 líneas mezcla un fix real con cambios no relacionados y un breaking change. Revisa como un maintainer: conserva lo que pertenece, señala lo que no.
Parte 2 de 3
Entender a quién rompe
Ya lo señalaste. Ahora la pregunta incómoda: ¿romper para quién? La respuesta no es la misma para una librería que publicas que para dos servicios que despliegas juntos esta tarde.
SemVer en la práctica
Cuándo hacer bump major, minor o patch — y por qué SemVer es la herramienta equivocada para servicios. Con un formato de changelog que la gente sí lee.
Parte 3 de 3
Vivir con ello
El PR #214 se mergeó. El null ya es real y permanente, y no hay ni un test ni una línea de documentación que lo respalde. Quedan los dos trabajos que nadie celebra.
Escribe tests para fetchUpstream
El fix del timeout llegó pero nada lo prueba. Escribe los tests que consolidan el nuevo comportamiento antes de que pueda regresar silenciosamente.
Documenta el módulo gateway
fetchUpstream no tiene docs, ni ejemplos, ni documenta su null return no obvio. Escribe la documentación que el próximo contribuidor necesita para usarlo con seguridad.