cadence-ui/docs/releasing.md

# Releasing

Cadence UI now uses a package-first release model.

Default downstream consumers should install:

- `@ai-ui/ui`

Add `@ai-ui/tokens` only when the consumer app imports token helpers or lower-level token CSS
directly.

The source-copy registry flow still exists, but it is the optional customization path, not the
default release target. See [docs/registry.md](/Users/xd/project/cadence-ui/docs/registry.md)
for that mode.

## Release artifacts

Each release now has three artifacts:

- published packages for `@ai-ui/ui` and `@ai-ui/tokens`
- a repository tag in the form `cadence-ui-vX.Y.Z`
- a committed `registry/index.json` snapshot for source-copy consumers pinned to that tag

## Package policy

- `@ai-ui/ui` and `@ai-ui/tokens` are released as a fixed version pair
- `@ai-ui/ui` is the primary component import surface
- `@ai-ui/ui/styles.css` is the default stylesheet entrypoint for package consumers
- `@ai-ui/tokens` remains available for lower-level token helpers and direct CSS imports
- `apps/docs` is a consumer app, not a releasable package

The current workflows assume private scoped packages on the npm registry with `access:
restricted`. If this repo moves to another registry later, update the publish workflow and
consumer setup accordingly.

## Consumer install

Package consumers should install the packages directly:

```bash
pnpm add @ai-ui/ui
```

Then import from `@ai-ui/ui` and point Tailwind at the packaged source:

```tsx
import { Button } from "@ai-ui/ui";
```

```css
@import "tailwindcss";
@import "@ai-ui/ui/styles.css";
@source "../node_modules/@ai-ui/ui/src";
```

This flow is validated by `pnpm test:package:consumer`.

## When to create a changeset

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

- 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, or small consumer-visible corrections
- `minor`: new components, new props, new variants, new tokens, additive API work
- `major`: breaking contract changes that require consumer updates

Because `@ai-ui/ui` and `@ai-ui/tokens` are fixed together, version bumps move as a pair.

## Local maintainer commands

Run the canonical release gate locally with:

```bash
pnpm harness:validate:release
```

`pnpm release:validate` remains as a convenience alias to the same gate.

The canonical release gate runs:

- lint
- typecheck
- package unit tests
- package builds
- Storybook build
- Storybook accessibility validation
- registry metadata validation
- source-copy consumer smoke
- package consumer smoke
- Storybook smoke coverage

Create a versioned release change with:

```bash
pnpm changeset
```

Apply pending version bumps locally with:

```bash
pnpm release:version
```

Publish the packages manually, if needed, with:

```bash
pnpm release:publish
```

## Automated release flow

The automated release sequence is now:

1. A product or package PR merges to `main` with a changeset.
2. `Release Version PR` runs on `main`, executes `pnpm harness:validate:release`, and opens or updates a version PR via Changesets.
3. A maintainer reviews and merges that version PR.
4. `Create Release Tag` detects the package version change on `main` and creates `cadence-ui-vX.Y.Z`.
5. `Publish Packages` runs on the tag push, validates the tagged commit again, and publishes `@ai-ui/ui` and `@ai-ui/tokens`.

The tag is the stable source reference for source-copy consumers. The packages are the default
artifact for package consumers.

## CI workflows

### Pull request check

`Changeset Status` runs on pull requests and:

- requires a changeset for releasable package changes unless `no-changeset-needed` is applied
- validates pending changesets
- checks that `registry/index.json` is current
- runs the source-copy consumer smoke test
- runs the package consumer smoke test

### Version PR workflow

`Release Version PR` runs on pushes to `main` and:

- installs dependencies
- runs `pnpm harness:validate:release`
- opens or updates the version PR with `pnpm release:version`

### Tag workflow

`Create Release Tag` runs on pushes to `main` and:

- detects when the fixed package version pair changed
- creates `cadence-ui-vX.Y.Z`

### Publish workflow

`Publish Packages` runs on `cadence-ui-v*` tags and:

- verifies the tag matches the package version
- runs `pnpm harness:validate:release`
- publishes the packages with `NPM_TOKEN`

## Required secrets

The publish workflow currently requires:

- `NPM_TOKEN`: token with publish access to the `@ai-ui` scope on the configured npm registry

## Notes for maintainers

- Keep `packages/ui/src/index.ts` and package exports aligned with the published surface.
- Keep `registry/index.json` in sync even though package publish is now the default; source-copy consumers still rely on it.
- If a component lands without docs or tests, it should not move toward release yet.