145 lines
4.2 KiB
Markdown
145 lines
4.2 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
|
|
|
|
## 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
|