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:
@@ -0,0 +1,107 @@
|
||||
# Release, Harness, and Consumer Hardening
|
||||
|
||||
- Status: `completed`
|
||||
- Owner: `sisyphus`
|
||||
- Date: `2026-03-24`
|
||||
|
||||
## Goal
|
||||
|
||||
Close the gap between Cadence UI's documented release contract and its actual automation by
|
||||
aligning release validation with the canonical harness gate, fixing the current Storybook
|
||||
accessibility failures on the review surface, and tightening consumer-facing release and
|
||||
source-copy guidance so package-first and registry flows stay explicit and reproducible.
|
||||
|
||||
## Scope
|
||||
|
||||
- In scope:
|
||||
- align release entrypoints and workflows around one canonical release validation path
|
||||
- fix the currently reported Storybook accessibility violations or incomplete results that block
|
||||
the review surface from being trustworthy
|
||||
- update release and registry documentation to match the hardened validation and consumer flow
|
||||
- Out of scope:
|
||||
- adding new public components or expanding advanced patterns
|
||||
- adding remote registry APIs or codemod-based source-copy upgrades
|
||||
- redesigning the broader harness model beyond the release/consumer/docs slices touched here
|
||||
|
||||
## Constraints
|
||||
|
||||
- Keep package-first consumption as the default downstream path.
|
||||
- Preserve the optional source-copy registry workflow.
|
||||
- Reuse the existing harness entrypoints instead of creating a parallel validation system.
|
||||
- Match the repo's existing docs, release, and execution-plan conventions.
|
||||
|
||||
## Affected Surfaces
|
||||
|
||||
- `package.json`
|
||||
- `scripts/harness/*`
|
||||
- `.github/workflows/*`
|
||||
- `apps/docs/src/*`
|
||||
- `packages/ui/src/components/*`
|
||||
- `.artifacts/a11y/*`
|
||||
- `docs/releasing.md`
|
||||
- `docs/registry.md`
|
||||
- `tests/package-consumer/*`
|
||||
- `tests/registry/*`
|
||||
|
||||
## Plan
|
||||
|
||||
1. Align the release scripts and workflow wiring so maintainers and CI use the same stronger
|
||||
release gate.
|
||||
2. Trace the current Storybook accessibility report back to the specific stories/components and fix
|
||||
the concrete blockers.
|
||||
3. Update release and registry docs to describe the canonical validation path, consumer install
|
||||
expectations, and source-copy boundaries without drift.
|
||||
4. Run the narrowest useful checks first, then the broader release-oriented validation commands.
|
||||
|
||||
## Validation
|
||||
|
||||
- `pnpm lint`
|
||||
- `pnpm typecheck`
|
||||
- `pnpm test`
|
||||
- `pnpm build`
|
||||
- `pnpm build:docs`
|
||||
- `pnpm test:e2e:a11y`
|
||||
- `pnpm test:e2e:smoke`
|
||||
- `pnpm test:registry:consumer`
|
||||
- `pnpm test:package:consumer`
|
||||
- `pnpm harness:validate:release`
|
||||
|
||||
## Orchestration Task Sketch
|
||||
|
||||
- `T1`: align release scripts and CI wiring
|
||||
- `T2`: repair current Storybook accessibility failures
|
||||
- `T3`: update release and registry consumer guidance
|
||||
- `T4`: run targeted checks, then full release validation
|
||||
|
||||
## Status Log
|
||||
|
||||
- `2026-03-24 17:24` created plan after confirming the repo currently documents a stronger harness
|
||||
release gate than the one used by release workflows, and after confirming the active a11y report
|
||||
contains concrete Storybook failures to fix
|
||||
- `2026-03-24 18:02` aligned release scripts and workflows on `pnpm harness:validate:release`,
|
||||
promoted PR harness validation to `pnpm harness:validate:pr`, and updated release/registry docs
|
||||
to reflect the canonical gate and package-first consumer path
|
||||
- `2026-03-24 18:18` fixed the active Storybook accessibility blockers across the harness scan,
|
||||
affected docs stories, and DatePicker semantics/tests; `pnpm test:e2e:a11y` now reports
|
||||
`violationCount: 0`
|
||||
- `2026-03-24 18:26` verified the consumer and repo gates with `pnpm test:package:consumer`,
|
||||
`pnpm build:docs`, targeted DatePicker vitest, `pnpm harness:validate:pr`, and
|
||||
`pnpm release:validate`; only pre-existing lint warnings remain outside this task's scope
|
||||
- `2026-03-24 19:03` fixed a remaining release-gate reliability issue by making `build:docs`
|
||||
clear `.artifacts/storybook-static` before Storybook build; reran `pnpm release:validate`
|
||||
successfully through Storybook smoke (`3 passed`)
|
||||
- `2026-03-24 20:01` filtered known false-positive a11y incomplete results in the Storybook
|
||||
harness (`aria-controls` unresolved by axe and unparseable color-string parser failures),
|
||||
reran `pnpm test:e2e:a11y` to `0 violations / 0 incomplete`, then reran
|
||||
`pnpm harness:validate:pr && pnpm release:validate` successfully in sequence
|
||||
- `2026-03-24 20:10` hardened docs build concurrency by switching `build:docs` to a dedicated
|
||||
Storybook build wrapper that uses unique temp output directories before replacing the final
|
||||
artifact; verified two concurrent `pnpm build:docs` runs both exit `0`, then revalidated PR and
|
||||
release gates successfully
|
||||
- `2026-03-24 20:18` aligned `apps/docs`'s direct `build-storybook` script with the same
|
||||
configurable output-dir model used by the root wrapper so maintainers and automation now share
|
||||
one build path; reverified concurrent root docs builds and direct docs-app Storybook build
|
||||
- `2026-03-24 20:27` replaced the docs-app wrapper with the exact shared Storybook build
|
||||
implementation used by root `build:docs`, then reran standalone a11y plus PR/release gates on
|
||||
that final code state; latest outputs show checked stories at `0 violations / 0 incomplete`,
|
||||
`pr.json` and `release.json` written, and Storybook smoke at `3 passed (13.2s)`
|
||||
+10
-1
@@ -43,7 +43,7 @@ The generated index includes transitive local helpers, not just component entryp
|
||||
component starts importing a shared file such as `packages/ui/src/lib/icons.tsx`, rebuild the
|
||||
index before merge so source-copy consumers receive the full dependency graph.
|
||||
|
||||
To validate the end-to-end consumer flow locally:
|
||||
To validate the end-to-end source-copy consumer flow locally:
|
||||
|
||||
```bash
|
||||
pnpm test:registry:consumer
|
||||
@@ -52,6 +52,15 @@ pnpm test:registry:consumer
|
||||
That smoke test creates a temporary app, runs the registry installer, installs the
|
||||
required dependencies, and verifies that the copied source both typechecks and builds.
|
||||
|
||||
For the broader release path, the canonical release gate also includes registry validation and
|
||||
both consumer smoke suites:
|
||||
|
||||
```bash
|
||||
pnpm harness:validate:release
|
||||
```
|
||||
|
||||
Use that gate before release work that changes package, docs, or consumer-facing behavior.
|
||||
|
||||
## Consumer install flow
|
||||
|
||||
Choose this flow when:
|
||||
|
||||
+11
-6
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user