dist-tags para releases: publicar next y beta sin mover latest

Sacar la próxima versión mayor sin que estalle en producción de miles de proyectos parece imposible, y sin embargo es rutina diaria en el ecosistema. El truco vive en un mecanismo humilde y mal comprendido: el dist-tag. Es un puntero con nombre —como una rama de git, pero sobre versiones ya publicadas— que desacopla qué versiones existen de cuál recibe el usuario por defecto. Publicar es un acto irreversible; distribuir es completamente reversible. Dominar esa distinción es poder iterar en público sin cortarle el build a nadie.

Publicar frente a distribuir

Un registro es, en el fondo, un log de solo-añadir: cada versión que publicas es un objeto inmutable que nunca cambiará ni se sobrescribirá. Sobre ese almacén append-only, un dist-tag es una referencia móvil, exactamente como main en git no es un commit sino un puntero a uno. latest no es una versión: es el puntero que el registro considera actual.

Su privilegio es único: cuando alguien escribe npm install @acme/ui sin pedir versión, el registro resuelve lo que señala latest. Ese único puntero decide qué recibe por defecto todo el que llega sin especificar nada. Y como es móvil, moverlo cambia al instante qué código sirve una instalación limpia sin tocar una línea del paquete.

Por eso npm publish mueve latest a la versión recién subida salvo que le indiques lo contrario, y ahí está el peligro: si publicas una prerelease inestable y dejas que latest la señale, se la sirves de golpe a cada instalación nueva del mundo. La solución es publicar bajo otro puntero, dejando latest anclado en la última estable. Instalar una línea concreta es tan simple como nombrar su tag.

La separación se sostiene sobre dos capas de naturaleza opuesta:

• Capa inmutable: las versiones. Una vez publicada, 3.0.0-beta.1 existe para siempre y su contenido no cambia jamás.
• Capa mutable: los tags. latest, next o beta son punteros que se mueven sin republicar nada.

flowchart LR
V1[2.5.0 estable] --> V2[3.0.0-beta.1]
V2 --> V3[3.0.0-rc.1]
V3 --> V4[3.0.0 estable]
L[tag latest] --> V1
N[tag next] --> V3
LM[latest se mueve al promover] -.-> V4
style L fill:#a6e3a1,color:#11111b
style N fill:#fab387,color:#11111b
style LM fill:#a6e3a1,color:#11111b

La doble red: dist-tag y exclusión de prereleases

Los dist-tags no trabajan solos: se apoyan en una regla profunda de SemVer que actúa como segundo cerrojo. Una versión de prerelease —3.0.0-beta.1, 3.0.0-rc.0— lleva tras el guion un identificador que la marca como incompleta, y la especificación es tajante: los rangos normales no capturan prereleases. La consecuencia se resume en dos hechos:

• Un ^2.4.0 jamás resolverá a 3.0.0-beta.1, aunque sea numéricamente mayor: un rango sin prerelease explícita ignora por diseño todo lo que lleve guion.
• Solo recibe una prerelease quien la pide de forma deliberada, nombrando el tag o escribiendo un rango que la incluya, como 3.0.0-beta o el truco ^3.0.0-0.

Así, aunque por descuido publicaras una beta y latest se moviera hacia ella, quien tenga fijado un rango estable seguiría intacto: su resolución nunca contempla la prerelease. Son dos mecanismos ortogonales que se combinan: el dist-tag decide qué señala el puntero por defecto, y la regla de prereleases garantiza que los rangos existentes ni se enteren de las versiones marcadas como experimentales.

Abrir canales y promover

El flujo práctico combina el flag --tag al publicar con la familia npm dist-tag para inspeccionar y mover punteros después. Publicar una prerelease es versionar con sufijo y subirla bajo un tag no estable; promoverla a estable, más tarde, es solo mover latest —sin republicar el artefacto, que ya existe inmutable.

# publica una prerelease sin tocar a los usuarios estables
npm version 3.0.0-beta.1
npm publish --tag next

# inspecciona y mueve punteros despues
npm dist-tag ls @acme/ui
npm dist-tag add @acme/ui@3.0.0 latest   # promover es mover un puntero
npm dist-tag rm @acme/ui next            # retira el canal cuando sobra

# instala una linea concreta de forma deliberada
npm install @acme/ui@next

Las convenciones del ecosistema son estables y conviene reconocerlas, porque un nombre bien elegido comunica intención sin documentación:

• latest: la última estable; el defecto de cualquier instalación.
• next: la próxima mayor en preparación, usable pero no definitiva.
• beta y alpha: fases tempranas, con la API aún en movimiento.
• rc: release candidate, una beta que aspira a estable sin más cambios.
• canary o nightly: builds automáticos por commit, para el filo absoluto.
• legacy: una línea mayor antigua que aún recibe parches de mantenimiento.

El tag legacy merece nota aparte: mantiene viva una versión mayor anterior —parches de seguridad para quien no ha migrado— sin que latest deje de señalar la línea actual. Distribuir dos líneas en paralelo es, otra vez, cuestión de punteros, no de código.

Del lado de quien consume, elegir la línea es igual de explícito, y cada forma pide un puntero o un rango distinto:

# instalar cada linea de forma explicita
npm i @acme/ui              # el puntero latest, la version estable
npm i @acme/ui@next         # la linea de preestreno
npm i @acme/ui@3.0.0-beta.1 # una prerelease exacta y fijada
npm i @acme/ui@^3.0.0-0     # un rango que SI admite prereleases de la 3

El sufijo -0 del último rango es el truco que le dice al resolutor que, esta vez, sí considere las prereleases de esa línea mayor: es la puerta que el consumidor abre voluntariamente cuando quiere vivir en el filo de una versión concreta.

Automatizar el canal desde la rama

En proyectos serios nada de esto se hace a mano: la máquina deriva el tag de la rama, de modo que empujar a una rama concreta publica en el canal correcto sin intervención humana.

• changesets: con changeset pre enter next entra en modo prerelease y dirige cada publicación al tag next; al cerrar la beta, pre exit vuelve a latest.
• semantic-release: mapea ramas a canales —main a latest, beta a beta— y elige el número y el tag desde los commits, sin flags manuales.
• canary por commit: un job publica versiones sintéticas tipo 0.0.0-canary seguidas del hash corto bajo el tag canary, para probar cada commit sin tocar latest.

# changesets: modo prerelease de la linea next
npx changeset pre enter next
npx changeset publish   # cada release sale bajo el dist-tag next
npx changeset pre exit  # al cerrar la beta, vuelve a latest

Las señales que la máquina traduce en un tag son explícitas y auditables:

• la rama a la que empujas, que mapea a un canal fijo;
• los mensajes de commit convencionales que marcan el nivel del cambio;
• los changesets acumulados que declaran la intención por pull request.

El principio común es que la máquina, no la memoria del humano, elige el número y el dist-tag a partir de esas señales. Publicar deja de ser un ritual manual y se vuelve una consecuencia determinista de fusionar código, con cada canal firmado por su propia procedencia desde CI.