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

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, registry credentials, and CI release automation 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

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

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 typecheck
pnpm test

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

pnpm build:docs
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, run the Changesets version step:

pnpm changeset version

That step is expected to:

• update package versions
• update internal dependency ranges where needed
• consume the pending changeset files

Review the resulting package diffs carefully before merging.

5. Publish or tag

Publishing is not fully wired in this repo yet, so treat this step as pending infrastructure.

The intended future flow is:

pnpm changeset publish

But until registry, auth, and CI behavior are explicit, do not assume publish is automated.

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 adds config and process docs only. To make it operational, the repo still needs:

• @changesets/cli added to root devDependencies
• root scripts such as changeset, version-packages, or release
• a decision on whether private packages should be published, mirrored internally, or versioned only
• CI wiring for version PRs and/or publish jobs