Versionado semántico forzado: cuando el número de versión deja de ser una opinión

El versionado semántico es una de las convenciones más citadas y menos cumplidas de la industria. La regla es célebre y sencilla: el primer número cambia cuando se rompe la compatibilidad, el segundo cuando se añade funcionalidad compatible y el tercero cuando solo se corrigen fallos. Todo el mundo la conoce, todo el mundo dice seguirla y todo el mundo ha sufrido una actualización de tercer número que destrozó una construcción que llevaba meses funcionando. La razón del incumplimiento no es la mala fe sino la estructura del asunto: el número lo elige la persona que publica, en el momento de publicar, basándose en su recuerdo de los cambios que ha hecho y en su juicio sobre si alguno rompe algo. Es una promesa emitida por quien no paga el coste de incumplirla y que nadie comprueba. Elm hizo con este problema exactamente lo mismo que había hecho con los errores en tiempo de ejecución: en vez de pedir más disciplina, eliminó la posibilidad de fallar. El número de versión de un paquete de Elm no lo escribe su autor, lo calcula una herramienta comparando la interfaz pública nueva con la publicada, y el registro se niega a aceptar cualquier otro.

El número de versión como promesa incumplible

Conviene ver el problema como un asunto de incentivos y de información antes que de disciplina. Quien publica un paquete tiene información parcial sobre lo que rompe: sabe qué ha tocado, pero no siempre sabe qué de lo que ha tocado formaba parte de la superficie pública, ni qué usos remotos dependen de un detalle que él consideraba interno. Tiene además un incentivo suave hacia el número pequeño, porque una ruptura obliga a escribir notas de migración y desalienta la actualización. Y tiene un coste cero por equivocarse, porque el fallo lo sufren otros en máquinas que él no ve. Con esos tres ingredientes, la única sorpresa es que la convención funcione tan a menudo.

La consecuencia se paga en la otra punta. Como nadie puede confiar en el número, los consumidores fijan versiones exactas, dejan de actualizar, acumulan deuda y terminan haciendo saltos enormes en los que se rompe todo a la vez. El mecanismo pensado para permitir actualizaciones seguras acaba produciendo ecosistemas congelados, y ese resultado no es culpa de nadie en particular: es lo que ocurre cuando una garantía depende de un juicio humano repetido miles de veces.

Hay además un problema de definición que agrava el anterior y que casi nunca se nombra. Para decidir si un cambio rompe la compatibilidad hace falta saber qué era exactamente lo prometido, y en la mayoría de los ecosistemas esa frontera no está escrita en ninguna parte: se distingue entre lo público y lo interno por convención tipográfica, por documentación o por costumbre, y en cuanto un consumidor depende de algo que el autor consideraba privado, el desacuerdo sobre si hubo ruptura es irresoluble porque las dos partes tienen razón. Sin una frontera declarada y comprobable, la pregunta de si esto rompe algo no tiene respuesta objetiva, y por tanto tampoco puede tenerla el número de versión.

La interfaz pública como valor comparable

La idea que resuelve el problema es que la interfaz pública de un paquete de Elm es un dato: la lista de módulos expuestos, y dentro de cada uno la lista de tipos, alias y valores con sus firmas completas. El compilador ya conoce ese dato porque lo necesita para compilar, y por tanto puede escribirlo, guardarlo junto a la versión publicada y compararlo después con el de la versión nueva. Comparar dos listas de firmas es una operación mecánica cuyo resultado se clasifica sin ambigüedad en tres categorías, y cada categoría determina qué número tiene que subir.

# Comparar la version local con la publicada
elm diff

# Comparar dos versiones publicadas de un paquete ajeno
elm diff elm/http 1.0.0 2.0.0

This is a MAJOR change.

---- MODULOS ELIMINADOS - MAJOR ----

    Http.Progress


---- Http - MAJOR ----

    Added:
        type Body
        header : String -> String -> Header

    Removed:
        type alias Response
        send : Request a -> Cmd msg

    Changed:
      - get : String -> Decoder a -> Request a
      + get : { url : String, expect : Expect msg } -> Cmd msg

Publicar: el registro decide tu número

El flujo completo es corto y no admite atajos. El autor pide a la herramienta que calcule la versión siguiente, la herramienta compara la interfaz local con la última publicada, clasifica el cambio y escribe el número resultante en el archivo de dependencias. Cuando después se intenta publicar, el registro repite la comprobación por su cuenta y rechaza el envío si el número no coincide con el que le corresponde. No hay una opción para forzarlo, no hay un argumento que salte la validación y no hay un modo experto.

# La herramienta calcula la version, no la eliges tu
elm bump
# Compared to the most recent version on the package website (1.0.0),
# this is a MINOR change. The new version is 1.1.0.

# Publicar: el registro vuelve a comprobarlo todo
elm publish

El registro comprueba además otras cosas en el mismo paso, y el conjunto explica por qué el catálogo de Elm tiene una consistencia poco frecuente. Todo paquete debe empezar en la primera versión estable, de modo que no existe el limbo de las versiones cero donde la convención declara que nada garantiza nada. Toda función expuesta debe llevar documentación, y la documentación se valida al publicar en lugar de generarse a posteriori. Las restricciones de dependencia se expresan siempre como un intervalo con extremo inferior incluido y superior excluido, lo cual permite que el resolutor razone sobre ellas sin heurísticas. Y ningún paquete puede incrustar código JavaScript arbitrario, lo cual mantiene el análisis completo y evita que una dependencia introduzca comportamientos que el sistema de tipos no ve.

flowchart LR
A[Interfaz publicada] --> C[Comparador]
B[Interfaz local] --> C
C --> M[Solo adiciones: menor]
C --> X[Eliminaciones o cambios: mayor]
C --> P[Sin cambios: parche]
M --> R[Registro acepta]
X --> R
P --> R
C --> N[Numero incorrecto: rechazo]
style C fill:#cba6f7,color:#11111b
style R fill:#a6e3a1,color:#11111b
style N fill:#f38ba8,color:#11111b

Hay un efecto secundario de este régimen que conviene señalar porque cambia la forma de diseñar bibliotecas. Como exponer algo es un compromiso que solo se puede deshacer subiendo el primer número, el autor aprende muy deprisa a exponer lo mínimo, y en particular aprende a preferir los tipos opacos, cuyos constructores no se publican, sobre los tipos abiertos. Un tipo cuyos constructores están expuestos convierte cada uno de ellos en parte del contrato y hace que añadir un caso interno sea una ruptura; un tipo opaco acompañado de funciones de construcción y de consulta permite reorganizar la representación entera sin que la interfaz se mueva. La herramienta no obliga a ese estilo, pero lo recompensa tan claramente que el catálogo entero converge hacia él.

Lo que la comparación no puede ver

La delimitación honesta de la garantía es tan importante como la garantía misma. El comparador ve tipos, no significados, y de ahí se sigue una clase entera de rupturas que pasan el filtro sin despeinarse. Una función que conserva su firma exacta y cambia de comportamiento —que empieza a ordenar al revés, que redondea de otro modo, que devuelve el error en vez de un valor por defecto, que pasa a distinguir mayúsculas— se publica como parche con toda legitimidad formal y rompe a sus usuarios igual que una eliminación. Un cambio en el formato de los datos que un paquete envía por un puerto tampoco se ve. Y una degradación seria del rendimiento es invisible por completo.

Hay también un límite en la dirección contraria, menos grave pero incómodo en la práctica: el comparador es estricto y no entiende de intenciones, así que clasifica como ruptura cambios que en rigor no rompen a nadie. Renombrar un parámetro con nombre en un record de argumentos, generalizar una firma para que acepte más casos de los que aceptaba o reordenar constructores expuestos cuentan como modificación de la interfaz y obligan a subir el primer número aunque ningún consumidor real se vea afectado. La regla prefiere equivocarse por exceso, que es la elección correcta para una garantía, pero produce paquetes cuyo primer número avanza más deprisa de lo que la intuición esperaría.

-- Misma firma, semantica distinta: pasa como PATCH sin objecion
ordenar : List Int -> List Int
ordenar = List.sort


ordenar : List Int -> List Int
ordenar = List.sort >> List.reverse