Feat/beta experimental releases by switzerb · Pull Request #1000 · gohypergiant/standard-toolkit

switzerb · 2026-05-08T02:45:37Z

Closes Issue 111

Overview

This PR implements two new release channels for the standard-toolkit monorepo:

Beta releases: Pre-stable release candidates with full quality bar
Experimental releases: Time-boxed (1 month) API sketches with minimal quality bar

Both workflows run alongside the existing stable release workflow without modifying it.

What's Implemented

✅ Beta Release Workflow ─

Scripts: beta:start, beta:exit, beta:status
Workflow: .github/workflows/release-beta.yml
-docs/BETA_RELEASE.md - TSC runbook for beta workflow
Triggers on beta/** branches
Publishes with @beta tag

✅ Experimental Release Workflow

Workflow: .github/workflows/publish-experimental.yml
Manual dispatch only, experimental/* branches
docs/EXPERIMENTAL_RELEASE.md - Guide for experimental releases
Publishes with @<feature-name> tag
Auto-comments on PRs

✅ Age Tracking ─

Workflow: .github/workflows/experimental-age-tracker.yml
Daily cron at 9 AM UTC
Escalating warnings at 14/21/28+ days

✅ Documentation

docs/BETA_RELEASE.md - TSC runbook for beta releases
docs/EXPERIMENTAL_RELEASE.md - Experimental workflow guide
.github/PULL_REQUEST_TEMPLATE/experimental.md

📝 Test Instructions

Unfortunately, because the beta and the experimental workflows require merging to the default branch (main) before they can be run against another branch (beta/* or experimental/*), this PR will have to merge before we can do a run through.

However, in each workflow there is a "dry-run" flag that will prevent publication to npm while we are running. I have set the "dry-run" flag to true as a default to be extra cautious.

I am able to run the age tracker that posts PR comments to the experimental branches and so can confirm that is working as expected:

Prerequisites for testing:

workflow scripts are on the main branch
branches exist for respective flows (beta/** or experimental/**)
.changeset files present for versioning

Dry Run Steps:
1. Navigate: Actions → "Beta Release" workflow
2. Trigger: "Run workflow" → enable "Dry-run mode" checkbox
3. Verify workflow output:
- ✅ Prerelease mode verification (mode: "pre", tag: "beta")
- ✅ Quality gates pass (build, lint, test)
- ✅ Version changes shown with -beta.N suffix 0
- ✅ Package list shows which packages would be published
- ✅ Installation commands shown for @beta tag
1. Confirm: No actual npm publish, no version PR created
2. Confirm: libraries versions are correct
Success Criteria:
- Workflow summary clearly labels dry-run mode
- Only changed packages get new beta versions (independent versioning)
- No side effects on npm registry or repository
Experimental Release Test

Setup Context:
- Experimental is for time-boxed API sketches (1-month max)
- Minimal quality bar (build + lint only, tests optional)
- Versions: X.Y.Z-experimental--
- npm tag: @
Dry Run Steps:
1. Navigate: Actions → "Publish Experimental Snapshot" workflow
2. Trigger: "Run workflow" on experimental/* branch → enable "Dry-run mode"
3. Verify workflow output:
- ✅ Feature name extracted correctly (e.g., experimental/test-run → test-run)
- ✅ npm tag matches feature name (@Test-Run)
- ✅ Quality gates pass (build, lint) ─
- ✅ Snapshot version format shown: X.Y.Z-experimental--
- ✅ Dry-run publish output lists packages
1. Confirm: No PR comment created, no actual npm publish
2. Confirm: libraries versions are correct
Success Criteria:
- Workflow summary shows extracted feature name and tag
- Timestamp-based versioning shown
- No side effects on npm registry or PR comments
Post-Test Validation

For both workflows:
- Check npm registry: npm dist-tag ls @accelint/design-toolkit (no new tags)
- Check repo: no new commits, PRs, or comments created
- Confirm dry-run mode banner visible throughout workflow summary

✅ Pull Request Checklist

Included link to corresponding GitHub Issue.
The commit message follows conventional commit extended guidelines.
Added/updated unit tests and storybook for this change (for bug fixes / features).
Added/updated visual regression tests for this change (for bug fixes / features).
Added/updated documentation (for bug fixes / features)
Filled out test instructions.
Added changeset (for bug fixes / features).

❓ Does this PR introduce a breaking change?

No. These are additive features:
New workflows don't affect existing stable release workflow
New scripts don't conflict with existing commands
New branch patterns (beta/**, experimental/*) are distinct

Yes
No

🤖 AI Usage

Added corresponding label (ai / human) to PR:

If ai was used, select all that apply:

Ideation / brainstorming
Documentation
Testing
Implementation

💬 Other information

vercel · 2026-05-08T02:45:43Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
design-toolkit	Ready	Preview, Comment	May 21, 2026 10:11pm
map-toolkit	Ready	Preview, Comment	May 21, 2026 10:11pm

github-actions · 2026-05-08T02:53:33Z

📊 Coverage Reports

Coverage Changes by Package

Click to expand 29 package details

apps/next (No diff)

packages/bus (No diff)

packages/constants (No diff)

packages/converters (No diff)

packages/core (No diff)

packages/dataset (No diff)

packages/design-foundation (No diff)

packages/design-toolkit (No diff)

packages/formatters (No diff)

packages/geo (No diff)

packages/hotkey-manager (No diff)

packages/icons (No diff)

packages/logger (No diff)

packages/map-toolkit

metric	current	base	change
lines	68.78%	70.12%	-1.34
statements	68.72%	70.09%	-1.37
functions	70.91%	73.28%	-2.37
branches	62.07%	62.06%	0.01

packages/math (No diff)

packages/ntds (No diff)

packages/postcss-tailwind-css-modules (No diff)

packages/predicates (No diff)

packages/temporal (No diff)

packages/web-worker (No diff)

packages/websocket (No diff)

tooling/biome-config (No diff)

tooling/constellation-tracker (No diff)

tooling/eslint-config (No diff)

tooling/prettier-config (No diff)

tooling/smeegl (No diff)

tooling/turbo-filter (No diff)

tooling/typescript-config (No diff)

tooling/vitest-config (No diff)

_{Coverage data collected from all packages in the monorepo.}

colehart · 2026-05-13T19:11:40Z

+            const prNumber = ${{ steps.pr.outputs.result }};
+            const packages = JSON.parse(process.env.PACKAGES);
+            const featureName = process.env.FEATURE_NAME;
+            const publishDate = new Date().toISOString().split('T')[0];


Can make this a little more explicit to follow the first published / last published stuff for that 1-month time box:

Suggested change

const publishDate = new Date().toISOString().split('T')[0];

const today = new Date().toISOString().split('T')[0];

colehart

Idea about first published / last published since there's a 1 month timebox. Take it or leave it. Just a couple nits otherwise

Co-authored-by: colehart <cole.hart@hypergiant.com>

… into feat/beta-experimental-releases

switzerb added 2 commits May 7, 2026 19:15

feat: add docs for release changes

22a87d2

feat: implementation of release flow

1170624

vercel Bot deployed to Preview – map-toolkit May 8, 2026 02:46 View deployment

vercel Bot deployed to Preview – design-toolkit May 8, 2026 02:47 View deployment

feat: add dry-run option for testing

4de84ab

switzerb added the ai AI was used in some way in this PR label May 8, 2026

switzerb marked this pull request as ready for review May 8, 2026 22:31

switzerb requested review from belsrc, brandonjpierce and shadyendless as code owners May 8, 2026 22:31

vercel Bot deployed to Preview – map-toolkit May 8, 2026 22:32 View deployment

vercel Bot deployed to Preview – design-toolkit May 8, 2026 22:33 View deployment