Versioning and deprecation
What counts as a breaking change in TaishoDS Core, how long a deprecated API lives, and how each version is released.
SemVer and the API surface
TaishoDS Core follows SemVer. A change is breaking (major) when it breaks something on the public surface. Everything else is minor (features, new components) or patch (fixes with no new API).
| Surface | Changing/removing it is |
|---|---|
| Core classes and modifiers (ts button, variant-*, size-*, is-*) | major |
| Core data-ts-* attributes and ts:* events | major |
| Functions exported from taisho.core.js (init, toast, setTextareaLoading…) | major |
| CSS token names (palette --color-* and semantic --ts-*) | major |
| Utilities documented in /docs/utilities | major |
| Undocumented internal classes, components’ internal HTML | minor/patch |
| Visual token values (a shade changes hue) | minor |
While the version starts with 0
Deprecation window
This policy applies from 0.15.0, the first public version of TaishoDS Core.
- A deprecated API lives for at least 2 minors before it can be removed. It is removed in a major; while there is none (before 1.0.0), in a minor.
- While it’s deprecated, it keeps working, it’s marked
@deprecatedin the type (visible in your editor), it emitsconsole.warnin dev only, and its docs point to the replacement. - No API is removed without going through a deprecation cycle published in the changelog.
Release cadence
There’s no fixed schedule. A new version ships when enough value has built up (minors) or when a bug affects the people using it (immediate patches). Each version has its entry in the changelog, in Spanish, with what changed and, if it breaks something, what to do to update.
How to update
Before moving to a new version, read its entry in the changelog: if something breaks, it says what and how to fix it. Then:
- Bump the version. With the CDN, change the number in the URL
(
/core/<version>/). Withtaisho generate, update@taishods/corewith npm and generate again. - Check your code against the system.
npx taisho checkflags what no longer paints: classes that don’t exist, missingtsscope classes, and variables that don’t exist. In CI,npx taisho generate --strictexits with 1 on any warning. - Look at the app in the browser. The visual values of tokens (a tone, a shadow) can change in a minor without being a breaking change.
# Update @taishods/core
npm install @taishods/core@latest
# Regenerate the CSS and the JS
npx taisho generate
# Check your code against the system
npx taisho checkWhere the changelog is
Every published version has its entry in the repository’s CHANGELOG.md. That’s where breaking changes, deprecated APIs, and their replacements are announced.