202 lines
6.3 KiB
Markdown
202 lines
6.3 KiB
Markdown
# 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: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.
|
|
|
|
### 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.
|