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

```bash
pnpm lint
pnpm typecheck
pnpm test
```

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

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

```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, run the Changesets version step:

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

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