Saltar al contenido

Versionado y deprecación

Qué es un breaking change en TaishoDS Core, cuánto vive un API deprecado y cómo se publica cada versión.

SemVer: qué es la superficie de API

TaishoDS Core sigue SemVer. Un cambio es incompatible (major) cuando rompe algo de la superficie pública; todo lo demás es minor (features, componentes nuevos) o patch (fixes sin API nueva).

Superficie Cambiarla/eliminarla es
Clases y modificadores del Core (ts button, variant-*, size-*, is-*)major
Atributos data-ts-* y eventos ts:* del Coremajor
Funciones exportadas de taisho.core.js (init, toast, setTextareaLoading…)major
Nombres de tokens CSS (--color-* de paleta y --ts-* semánticos)major
Utilidades documentadas en /docs/utilitiesmajor
Clases internas no documentadas, HTML interno de componentesminor/patch
Valores visuales de tokens (un shade cambia de tono)minor

Mientras la versión empieza con 0

Antes de la 1.0.0 no hay versión major: un cambio incompatible sube la minor (de la 0.15 a la 0.16, por ejemplo) y un cambio compatible sube el patch. Lo que la tabla marca como major se anuncia igual, en el registro de cambios, con lo que hay que hacer. Desde la 1.0.0, todo cambio incompatible es una major.
El HTML interno de un componente y sus clases no documentadas no son API: apoyarse en ellos (CSS que targetea la estructura interna) puede romperse en cualquier minor sin aviso.

Ventana de deprecación

Esta política rige desde la 0.15.0, la primera versión pública de TaishoDS Core.

  • Un API deprecado vive al menos 2 minors antes de poder eliminarse. Se elimina en una major; mientras no exista una (antes de la 1.0.0), en una minor.
  • Mientras está deprecado: sigue funcionando, se marca @deprecated en el tipo (visible en el editor), emite console.warn solo en dev, y su doc indica el reemplazo.
  • Ningún API se elimina sin haber pasado por un ciclo de deprecación publicado en el registro de cambios.

Cadencia

No hay calendario fijo: se publica una versión nueva cuando hay valor acumulado (minors) o ante un bug que afecta a quien lo usa (patches inmediatos). Cada versión tiene su entrada en el registro de cambios, en español, con lo que cambió y, si rompe algo, lo que hay que hacer para actualizar.


Cómo actualizar

Antes de subir de versión se lee la entrada de esa versión en el registro de cambios: si algo rompe, dice qué y cómo resolverlo. Después:

  1. Subir la versión. Con el CDN, cambia el número en la URL (/core/<versión>/). Con taisho generate, se actualiza @taishods/core con npm y se vuelve a generar.
  2. Revisar el código contra el sistema. npx taisho check avisa lo que ya no pinta: clases que no existen, llaves ts que faltan y variables que no existen. En CI, npx taisho generate --strict sale con 1 ante cualquier aviso.
  3. Mirar la app en el navegador. Los valores visuales de los tokens (un tono, una sombra) pueden cambiar en una minor sin ser un cambio incompatible.
actualizar con taisho generate

Dónde está el registro de cambios

Cada versión publicada tiene su entrada en el CHANGELOG.md del repositorio. Allí se anuncian los cambios incompatibles, los API deprecados y su reemplazo.