| Reference | Value |
|---|---|
| Subject and boundary | Current release state, how a version is prepared, tagged, published and verified, and how a product adopts or rolls back a release. Product deployment is the product's. |
| Verified source | RELEASING.md, tools/release-core.ts, release.yml, product guide at tag v0.40.0. Verified tag v0.40.0, commit 43bba26a73dd0f7aa01cb7c8f37d697734b367ad, checked 2026-11-10; earlier passes checked 2026-11-09 and November 7, 2026. |
| Support state | Stable release support is v0.40.0. The release procedure is documented at this tag; product adoption and deployed acceptance are independently evidenced. |
| Layer | Contract |
|---|---|
| Supported release | v0.40.0: immutable stable release, eight package tarballs, same-release sibling peers. Only the latest stable line is supported. |
| Source | Annotated tag v0.40.0 resolves to 43bba26a73dd0f7aa01cb7c8f37d697734b367ad (#210). All eight package manifests are 0.40.0; private Gallery is 0.1.0. v0.40.0 promotes v0.40.0-rc.2 (#209), which added a @yesid/ui patch to rc.1 (#207): touch drags on bottom Sheet detents survive the handle's implicit pointer capture (#208). From rc.1, @yesid/seo-kit and @yesid/ui take content-derived descriptions and share-card text through resolveShareCopy (#197, minor), and all eight packages pack sibling peers at yesid-dev/yesid.design URLs (#202, patch) (CHANGELOG 0.40.0). The repository moved from mgkdante/yesid.dev-design to mgkdante/yesid.design at v0.36.1, then to the organization as yesid-dev/yesid.design on November 10, 2026. release.yml runs only in yesid-dev/yesid.design since #198 (1412d06f). v0.40.0-rc.1, v0.40.0-rc.2 and v0.40.0 are the first releases cut there. |
| Verification | gh release verify v0.40.0 passes. gh attestation verify of yesid-ui-0.40.0.tgz with --repo yesid-dev/yesid.design passes: provenance from yesid-dev/yesid.design release.yml at refs/tags/v0.40.0, commit 43bba26a73dd0f7aa01cb7c8f37d697734b367ad. The packed UI manifest names its tokens, motion and seo-kit peers at yesid-dev/yesid.design v0.40.0 URLs. GitHub lists an immutable stable release published November 10, 2026 at 16:25:49 UTC, with eight uploaded package assets, after prereleases rc.1 (14:47:58 UTC) and rc.2 (15:47:42 UTC). Checked 2026-11-10. Product rehearsal, adoption, deployment and runtime receipts belong to their owning records. |
| Product boundary | Publication does not adopt or deploy a product. Each product owns its bump, checks, deployed revision and runtime acceptance. Transit (#738, merge 6b5a9c80), yesid.dev (#692, merge 0461e045) and yesid.login (#34, merge 9356b884) adopted v0.40.0. Each PR was opened as a draft, carries rc.1 and rc.2 rehearsal commits and a stable adoption commit, left draft and merged on November 10, 2026. Their mains (Transit ed25527f, yesid.dev 3587e930, yesid.login d2074d24, read 2026-11-10) pin v0.40.0. |
A product adopts the tag's remembered-section contract and rebuilds with injectThemeBoot in the head before page content, package component CSS, and the exact @yesid/ui/boot.json CSP source. Privacy copy identifies origin-local sections-choice storage. Product checks cover first visit (content open, neutral Collapse all control) and both stored choices, reload and another route, blocked storage, disabled JavaScript, nested fragments, TOC, Back and locale reading-position restoration, responsive media/charts, reduced motion, delayed hydration and startup failure/recovery. Google indexing, rendered crawler behavior and product text exporters require product evidence.
sequenceDiagram
participant S as Source PR
participant R as Release PR
participant T as Tag on main
participant W as release.yml
participant C as Draft adoption PRs in Transit, yesid.dev and yesid.login
S->>S: changes + pending .changes fragments, CI green, merge
R->>R: prepare/check rc.N, CI green, owner API approval, merge
T->>W: push annotated vX.Y.Z-rc.N
W->>W: verify tag, check, test, pack 8 tgz, attest, publish immutable Release
W->>C: same immutable candidate in all three consumers
C->>C: own checks + affected real callers; only the prerelease guard fails
C->>R: promote identical proven source and approved API report
R->>W: stable release-only PR, annotated tag, publish
W->>C: same PRs switch to stable URLs + lockfile, rerun CI, leave draft, merge
Source changes merge with their fragments pending. Preparation is a separate release-only pull request after every source change for that version is on main: it consumes the fragments, so an API change merged afterwards needs its own new fragment, and release:check refuses to pass while any fragment is pending. Approved pull requests, release-only ones included, merge through the main merge queue: gh pr merge <number> --repo yesid-dev/yesid.design --auto --squash enqueues one. A release-only PR titled exactly chore(release): prepare vX.Y.Z, chore(release): prepare vX.Y.Z-rc.N or chore(release): promote vX.Y.Z takes a light CI lane, verified by a byte-for-byte reproduction of release:prepare. A byte-identical design-prerelease-guard.mjs in all three consumers blocks -rc URLs from reaching their main.
| Step | Command and guard |
|---|---|
| Prepare | bun run release:prepare -- --version X.Y.Z bumps the root and eight package manifests and the bun.lock workspace versions, folds fragments into CHANGELOG.md, deletes them and sets package README source links to blob/vX.Y.Z/. It refuses a fragment already consumed, and a version that does not match the highest requested bump, unless it advances a prerelease of the same core. |
| Check | bun run release:check -- --version X.Y.Z [--tag vX.Y.Z] requires matching manifests, no pending fragments, the version as the latest changelog section and every package README linking only the new tag. |
| Tag | From a clean detached origin/main: git tag -a vX.Y.Z -m vX.Y.Z, release:check with --tag, confirm gh api repos/yesid-dev/yesid.design/immutable-releases --jq .enabled is true, then push the tag ref. |
| Publish | release.yml checks the tag is annotated, reachable from main and matches the prepared version, runs check and test, rewrites each sibling workspace:* peer, and any already pinned design asset URL, to this release's yesid-dev/yesid.design asset URL (#202), copies LICENSE and NOTICE into each package, packs eight tarballs with bun pm pack, attests provenance and publishes with gh release create --verify-tag. A tag with a hyphen publishes as a prerelease. |
| Verify | gh release view <tag> --json assets, gh release verify <tag>, then download an asset and run gh attestation verify <tarball> against the repository the release was signed under. v0.40.0 and later: --repo yesid-dev/yesid.design. v0.36.1 to v0.39.1, signed as mgkdante/yesid.design: --owner mgkdante --signer-repo mgkdante/yesid.design. v0.36.0 and earlier, signed as mgkdante/yesid.dev-design: --owner mgkdante --signer-repo mgkdante/yesid.dev-design. On 2026-11-10 the signer form passed for yesid-ui-0.39.1.tgz, while --repo mgkdante/yesid.design returned HTTP 404. |
When an API report or migration note changes, prepare and publish X.Y.Z-rc.N on main. Owner API-report approval is required before the first candidate tag and again before a later candidate whose report changes. Candidate publication is public and immutable.
In each of Transit, yesid.dev and yesid.login, the three consumers RELEASING.md §4 names, a draft adoption PR from that product's current main installs the same candidate's exact URLs and lockfile, applies required migrations and app fixes, then runs its required checks and affected real callers. The only expected failures are prerelease-guard and the required ci aggregate in Transit and yesid.dev, and the guard step at the end of the required verify check in yesid.login. Record the design ref, all three products' base and tested head refs, CI runs, behavior, responsive, accessibility and reduced-motion results on the owning release record. Every other required job must pass, including all yesid.dev E2E shards. Gallery and generic fixtures cannot accept real product callers. First use: v0.39.0-rc.1 (#189 828ae652), promoted to v0.39.0 (#194 16ae4fde) and adopted in yesid.dev #666, Transit #699 and yesid.login #22 66107f65. v0.40.0 used two candidates: rc.1 (#207) and rc.2 (#209, after the sheet fix #208), rehearsed in yesid.dev #692, Transit #738 and yesid.login #34 and promoted unchanged in source as v0.40.0 (#210).
A shared defect gets a separate source PR with its regression, report and fragment, then a new candidate release-only PR and another rehearsal in all three draft adoption PRs. Stable promotion preserves the proven source and approved report; only version, pins, README links and changelog promotion may differ. The prerelease guard keeps candidate URLs out of product main; after stable promotion, each draft PR switches to the stable URLs, reruns its required CI and merges. Use the source and migration documentation for the candidate's exact tag.
| Action | Procedure |
|---|---|
| Adopt | In the product's own pull request, change the tag and version in every https://github.com/yesid-dev/yesid.design/releases/download/vX.Y.Z/yesid-<pkg>-X.Y.Z.tgz URL, including the UI peers (tokens, motion, seo-kit) and seo-kit's tokens peer. Run bun install, review the lockfile diff with the product's overrides, and run tests, typecheck, gates and the production build. Check the release notes for peer changes such as a Satori floor. |
| Roll back | Choose a rollback target accepted by the product. Set every package URL to that tag and version, align dependencies with its package set, then run the full product checks. Tarballs before v0.40.0 can name old-owner sibling URLs that rely on GitHub redirects (CHANGELOG 0.40.0-rc.1); verify them with the signer named in the Verify row. |
| Never | ^, ~, a branch or a floating tag; patching files under node_modules/@yesid; moving, deleting or re-pushing a tag; editing a published Release. |
| Situation | Recovery |
|---|---|
| Run failed before publishing | Check gh release view <tag>. gh release create deletes its draft on failure, but cleanup can fail: delete only a confirmed unpublished draft with gh release delete <tag>, then retry. |
| Transient failure | gh run rerun <run-id>. |
| The workflow itself needed a fix | Merge the fix to main, then gh workflow run release.yml -f tag=<tag>. The dispatch uses main's workflow but checks out, tests and packs the tagged source. |
| Defect in the tagged source | Fix forward with a new version. A published Release stays as it is. |