cadence-ui/docs/releasing.md

Releasing

This repo is not fully on a public-package release pipeline yet, but it is ready to use Changesets as the canonical record of release intent.

The current goal is modest:

• version @ai-ui/ui and @ai-ui/tokens deliberately
• keep release notes attached to the changes that caused them
• avoid inventing ad hoc version bumps when the component system evolves
• make release intent enforceable in CI before package work merges
• keep the generated registry metadata aligned with versioned source

Current assumptions

• The repository root is private.
• Workspace packages currently use explicit package versions even when they are not yet published.
• @ai-ui/docs is a consumer app, not a releasable package, so it is ignored by Changesets.
• Publishing mechanics and registry credentials are still to be added.

Because of that, this baseline is intentionally conservative.

Packages in scope

Changesets should currently be used for:

• @ai-ui/ui
• @ai-ui/tokens

Package consumers should now prefer:

• @ai-ui/ui for component imports
• @ai-ui/ui/styles.css for the combined token + skin stylesheet

The lower-level entries remain available when needed:

• @ai-ui/tokens/styles.css
• @ai-ui/ui/skins.css

Changes to the docs app alone usually do not need a changeset.

When to create a changeset

Create a changeset when a merged change affects any consumer-facing surface of a releasable package:

• new components or slots
• changed props or variants
• token additions or token behavior changes
• accessibility changes that alter behavior
• bug fixes that consumers will notice
• breaking contract changes

You can usually skip a changeset for:

• docs-only edits
• test-only edits
• internal refactors with no consumer-visible behavior change

If CI would otherwise require a changeset for one of those exceptions, apply the no-changeset-needed pull request label and explain the reason in the PR description.

Versioning guidance

Use semver pragmatically:

• patch: bug fixes, QA-only behavior fixes, docs fixes bundled with a small behavior correction
• minor: new components, new props, new variants, new tokens, additive API work
• major: breaking prop changes, renamed slots or states, removed variants, contract changes that require consumer updates

When in doubt, bias toward minor over underselling a visible new surface.

Recommended workflow

1. Make the code change

Complete the implementation, docs, and tests first.

At minimum, run:

pnpm lint
pnpm registry:check
pnpm typecheck
pnpm test

Use the docs and smoke checks when the change touches behavior-heavy UI:

pnpm build:docs
pnpm test:registry:consumer
pnpm test:e2e:smoke

2. Create a changeset

After the change is ready, create a changeset entry for the affected package or packages.

Once @changesets/cli is installed in the repo, the intended command is:

pnpm changeset

The generated markdown file should:

• select the impacted package(s)
• choose the correct version bump type
• include a short consumer-facing summary

3. Review internal dependency impact

This repo is configured to update internal dependencies with a patch bump.

That means if @ai-ui/tokens changes and @ai-ui/ui depends on it, the versioning step should keep the dependency graph coherent without requiring manual package edits.

4. Version the packages

When it is time to cut a release manually, run the repo version step:

pnpm release:version

That step is expected to:

• update package versions
• update internal dependency ranges where needed
• consume the pending changeset files
• rebuild registry/index.json so the copy-in install metadata stays version-aligned

Review the resulting package diffs carefully before merging.

On main, the repository also runs a Release Version PR workflow that opens or updates a version PR with the same command. That workflow is intentionally limited to version-file updates; it does not publish packages.

5. Distribute the versioned source

Publishing is not fully wired in this repo yet, so the consumable artifact is the versioned repository state itself.

After the version PR merges:

• keep the merge commit as a stable install point, or create a maintainer tag for it
• treat the committed registry/index.json as the install contract for that repo state
• point consumers at that commit or tag when they run pnpm registry:install

See docs/registry.md for the consumer install and upgrade flow.

CI workflows

Pull request check

The Changeset Status workflow runs on pull requests and enforces a simple rule:

• if a PR changes @ai-ui/ui or @ai-ui/tokens, it should usually include a new .changeset/*.md file
• if the work is intentionally non-releasable, maintainers can apply the no-changeset-needed label

When a changeset is present, the workflow also runs:

pnpm changeset:status --since origin/main

This validates that pending changesets resolve cleanly against the base branch.

The workflow also runs:

pnpm registry:check

This prevents registry metadata drift from merging unnoticed.

The repo also runs:

pnpm test:registry:consumer

This verifies that the committed registry snapshot can still install into a fresh consumer app, typecheck, and build.

Version PR workflow

The Release Version PR workflow runs on pushes to main and on manual dispatch. It:

• installs dependencies
• runs pnpm release:version
• opens or updates a version PR using changesets/action

This is still a versioning skeleton, not a publish pipeline, but the version PR now refreshes the committed registry metadata that consumers install from.

Future publish prerequisites

Before turning the version workflow into a publish workflow, the repo still needs:

• a root publish script, for example pnpm changeset publish or a guarded wrapper around it
• registry credentials such as NPM_TOKEN
• a decision on which workspace packages should actually be published versus versioned internally
• any extra validation that must run before publish is allowed

Notes for maintainers

• Keep packages/ui/src/index.ts and package exports aligned with any release-worthy surface.
• If a component lands without docs or tests, it should not move toward release yet.
• Prefer one clear changeset per consumer-visible change rather than bundling unrelated work.
• If a PR contains both infra and component work, separate the release notes so consumers can understand what actually changed.

Main-thread follow-up still needed

This baseline now covers changeset intent checks in PRs, registry metadata validation, and version PR creation on main. What remains is the publish decision, tagging policy, and any registry-specific automation beyond source-copy installs.