Skip to content

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:* eventsmajor
Functions exported from taisho.core.js (init, toast, setTextareaLoading…)major
CSS token names (palette --color-* and semantic --ts-*)major
Utilities documented in /docs/utilitiesmajor
Undocumented internal classes, components’ internal HTMLminor/patch
Visual token values (a shade changes hue)minor

While the version starts with 0

Before 1.0.0 there is no major version: a breaking change bumps the minor (from 0.15 to 0.16, for example) and a compatible change bumps the patch. What the table marks as major is announced all the same, in the changelog, with what to do about it. From 1.0.0 on, every breaking change is a major.
A component’s internal HTML and its undocumented classes are not API. Relying on them (CSS that targets the internal structure) can break in any minor without notice.

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 @deprecated in the type (visible in your editor), it emits console.warn in 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:

  1. Bump the version. With the CDN, change the number in the URL (/core/<version>/). With taisho generate, update @taishods/core with npm and generate again.
  2. Check your code against the system. npx taisho check flags what no longer paints: classes that don’t exist, missing ts scope classes, and variables that don’t exist. In CI, npx taisho generate --strict exits with 1 on any warning.
  3. 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.
updating with taisho generate

Where 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.