# 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`

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:

```bash
pnpm lint
pnpm registry:check
pnpm typecheck
pnpm test
```

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

```bash
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:

```bash
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:

```bash
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](/Users/xd/project/cadence-ui/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:

```bash
pnpm changeset:status --since origin/main
```

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

The workflow also runs:

```bash
pnpm registry:check
```

This prevents registry metadata drift from merging unnoticed.

The repo also runs:

```bash
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.