Versioning

Releases, pinning and upgrades

This handbook targets v1.1.0, published with an installable archive and execution evidence. Release assets and notes are the starting point for runtime consumption. npm registry publication is a separate owner action; use the archive instructions unless the exact npm version has actually been published.

What changed

Baseline	Meaning
v0.1.0	Historical specification release; do not follow its old palette or inventory claims for a new 1.1.0 integration
v1.0.0	Immutable major-version baseline introducing True Black / Rose, the portal and official package work
v1.1.0	Published additive themed-control correction, full-width command search and complete package/copy distribution

Do not retarget old pins. The True Black / Rose migration and changelog explain the design changes. A tag, public release assets, npm publication and successful deployment are separate things; check the artifact you intend to consume.

Resolve a tag correctly

git ls-remote https://github.com/j3w1/theme.git 'refs/tags/v1.1.0*'

For an annotated tag, the refs/tags/v1.1.0^{} entry is the underlying commit. Record that full commit rather than the tag-object ID. The HTTP equivalent starts at the Git ref API; follow tag objects until reaching the commit.

Use one tag/full revision in every source URL. Branch names and floating latest URLs are not consumption pins. The live website may advance after your integration; your pinned package and contracts do not automatically advance with it.

Upgrade a package consumer

1. Record the existing version, archive/lock identity, canonical revision and deviations.
2. Review target release notes, migration instructions and changed contracts.
3. Install the new archive in a clean fixture and exercise the components used by your app.
4. Update token CSS, component styles and runtime together. Remove conflicting copies of an older registration.
5. Check labels, validation, FormData, reset, disabled/read-only states, choices, dialogs, focus, reflow and lifecycle in the real app.
6. Update the package lock and canonical integration record together. Preserve required notices and disclosures.

For copies, generate into a new directory and review the complete closure against your locally modified files. The CLI deliberately refuses to overwrite an existing destination. Keep a known-good version and the application's normal rollback path.

For mapped hosts, compare semantic role assignments and supported surfaces, then regenerate the host artifact and test a real import. A successful parser run is not an import test.

Compare contracts deliberately

From a checkout with dependencies and the compared refs available:

npm run release:compare -- --from v0.1.0 --to v1.1.0 --out ../theme-comparison

Inspect value, alias, status/decision, component/state, portability and appearance-source differences. Known affected consumers are declared mappings, not observed production failures; unregistered consumers stay unknown.

What a version does not promise

A release does not approve a proposed profile, erase pending decisions, certify your app, or make every port verified. Read the exact contracts and evidence. The package's API declarations, implementation availability and actual execution results remain distinct.

Next: Quick start · Verification · Agent integration.