La página de código abierto que casi mintió sobre sus propios números de versión

Agregué una página de Código abierto a este sitio: /open-source/, que lista los cuatro paquetes de Astro que construí para mi propia familia de sitios y publico abiertamente en GitHub. Idea simple. Lo interesante fue casi publicar números de versión incorrectos en una página cuya premisa entera es “esto es lo que corre este sitio”.

Las versiones que revisé, y las versiones que importaban

El issue pedía una pequeña colección de contenido: un archivo markdown por paquete, con frontmatter para nombre, lema, versión, estado y puntos destacados. Antes de escribir código fui a revisar la etiqueta de versión más reciente en cada uno de los cuatro repos. astro-blog v0.7.0, astro-affiliate v0.4.0, astro-og-cards v1.0.0, astro-opt-in-analytics v0.5.1. Las escribí, construí la página, corrí el build.

Luego corrí la verificación de accesibilidad, que levanta un build real detrás de wrangler dev, y mientras corría le eché un vistazo al propio package.json de este sitio. Las versiones fijadas de las dependencias no coincidían con lo que acababa de escribir. astro-blog estaba en v0.6.2, astro-affiliate en v0.3.0, astro-opt-in-analytics en v0.5.0. Solo astro-og-cards coincidía, porque es la incorporación más reciente y no ha tenido ningún lanzamiento desde que este sitio la adoptó.

Así que la página recién construida le habría dicho a un visitante “este sitio corre v0.7.0 de astro-blog” cuando el sitio en realidad todavía corría v0.6.2. Nadie lo habría notado. No rompe nada. Es solo una pequeña falsedad dicha con confianza, en una página cuya premisa entera es que esto es real y yo mismo lo uso, el mismo modo de falla que la tarjeta de repos fijados que quedó desactualizada.

Cambié cada campo de versión a la etiqueta realmente fijada en el propio package.json de este repo, no a la última etiqueta upstream. Si más adelante actualizo una dependencia, la página y el lockfile pueden volver a desalinearse, pero al menos empieza siendo verdad.

La colección de contenido que no construí

Antes de todo eso, una decisión más pequeña que vale la pena mencionar. La propia sugerencia del issue era una colección de contenido real de Astro: archivos markdown con frontmatter validado con zod. Miré lo que en realidad estaba almacenando, un lema, tres viñetas destacadas, una cadena de versión, y me di cuenta de que no había ningún cuerpo de prosa en ninguna parte.

Una colección de contenido se justifica cuando hay un documento markdown real para escribir. Acá cada campo era un dato corto y estructurado, exactamente la forma para la que el sitio ya tenía un patrón que funcionaba con sus tarjetas de proyecto. Agregar todo un esquema y un loader para cuatro entradas que no tienen nada más que frontmatter era maquinaria construida para una función que no existía. Opté por el arreglo tipado simple en su lugar, y la página salió con un diff más pequeño gracias a eso.

Alcance que dejé deliberadamente de lado

Podría haber usado el mismo cambio para recortar la lista de paquetes en línea que ya existía en la portada, que ahora duplica parte de lo que muestra la página nueva. Lo dejé para después. Un seguimiento planeado (páginas de detalle por paquete) le dará a esa lista de la portada un lugar real al cual enlazar; recortarla ahora significaría que la portada deje de nombrar estos paquetes por un tiempo, sin nada todavía construido para reemplazarlo. El orden en que sale cada pieza de una función de varias partes importa tanto como construir bien cualquiera de esas piezas.

Lección

Nada de esto tardó mucho en arreglarse. Lo que vale la pena recordar es que “los paquetes que corren en este sitio” es una afirmación, y una afirmación vale tanto como aquello contra lo que se la verificó. Verifiqué lo incorrecto primero: la verdad upstream en vez de la verdad local, cuando la frase de la página hablaba de la verdad local.