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 Core | major |
| 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/utilities | major |
| Clases internas no documentadas, HTML interno de componentes | minor/patch |
| Valores visuales de tokens (un shade cambia de tono) | minor |
Mientras la versión empieza con 0
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
@deprecateden el tipo (visible en el editor), emiteconsole.warnsolo 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:
- Subir la versión. Con el CDN, cambia el número en la URL
(
/core/<versión>/). Contaisho generate, se actualiza@taishods/corecon npm y se vuelve a generar. - Revisar el código contra el sistema.
npx taisho checkavisa lo que ya no pinta: clases que no existen, llavestsque faltan y variables que no existen. En CI,npx taisho generate --strictsale con 1 ante cualquier aviso. - 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.
# Subir @taishods/core
npm install @taishods/core@latest
# Regenerar el CSS y el JS
npx taisho generate
# Revisar el código contra el sistema
npx taisho checkDó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.