docs: clarify release validation and consumer flows

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
2026-03-24 18:00:20 +08:00
parent 50c1e14303
commit c177fbefa4
3 changed files with 128 additions and 7 deletions
+11 -6
View File
@@ -87,21 +87,26 @@ Because `@ai-ui/ui` and `@ai-ui/tokens` are fixed together, version bumps move a
## Local maintainer commands
Run the release validation suite locally with:
Run the canonical release gate locally with:
```bash
pnpm release:validate
pnpm harness:validate:release
```
That command currently runs:
`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:
@@ -126,7 +131,7 @@ pnpm release:publish
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 release:validate`, and opens or updates a version PR via Changesets.
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`.
@@ -151,7 +156,7 @@ artifact for package consumers.
`Release Version PR` runs on pushes to `main` and:
- installs dependencies
- runs `pnpm release:validate`
- runs `pnpm harness:validate:release`
- opens or updates the version PR with `pnpm release:version`
### Tag workflow
@@ -166,7 +171,7 @@ artifact for package consumers.
`Publish Packages` runs on `cadence-ui-v*` tags and:
- verifies the tag matches the package version
- runs `pnpm release:validate`
- runs `pnpm harness:validate:release`
- publishes the packages with `NPM_TOKEN`
## Required secrets