1

Versioning

How ondo-ui's version number works and how it relates to the Changelog.

ondo-ui uses a MAJOR.MINOR.PATCH version number for the npm package (tracked in packages/ondo-ui-cli/package.json). The public website is private and keeps its hand-written bilingual Changelog separate from the package changelog that Changesets generates for npm.

What each digit means

DigitBumps when...Example
MAJORA breaking change shipsMigrating the CLI schema, or a breaking restructure across many components
MINORAn additive feature shipsA new component, composition, or util ships
PATCHA fix or other compatible adjustment shipsA bug is fixed, styles are tweaked, metadata is corrected

Bumping a higher digit resets every digit below it to 0 — same as standard semver (1.2.3 → a MAJOR change → 2.0.0).

One release, one bump

Each dated Changelog entry corresponds to exactly one version bump. If a release mixes multiple kinds of change (say, a new component ships alongside a fix to an existing one), only the highest-ranked digit bumps — MAJOR beats MINOR beats PATCH. You don't stack multiple bumps into one entry.

The version goes in the entry's frontmatter as version: 0.1.0, and is repeated at the top of the body (e.g. v0.1.0) so it reads well on the page.

The frontmatter field is what orders the Changelog. The filename only carries the date, and two releases can land on the same day — when they do, the version decides which comes first.

Release source of truth

Changesets is the source of truth for package releases. Feature branches should add a changeset with bun run changeset; the release process opens a Version Packages PR that applies those changesets to packages/ondo-ui-cli/package.json, updates packages/ondo-ui-cli/CHANGELOG.md, and refreshes the lockfile. Merge that PR to publish through the trusted npm publisher.

Keep the manually curated English and Korean website Changelog entries under content/docs/changelog/ separate from the generated npm package changelog. After the published 1.3.1 package, the next additive release is 1.4.0, which includes the Ondo CLI command surface.