Skip to main content
HyperFrames publishes two release channels:
  • Stable releases use versions like 0.4.24 and publish to the npm latest dist-tag.
  • Prereleases use versions like 0.4.24-alpha.1 and publish to the npm dist-tag named by the prerelease suffix, such as alpha.

​
Branch policy

Use branch separation to decide what code is eligible for each release channel. Dist-tags only control npm install defaults; they do not remove code from a package.
  • main is stable/releasable. Anything merged to main is eligible for latest.
  • release/v* branches are for stable patch releases and hotfixes.
  • next, alpha, beta, rc, canary, and prerelease/* branches are for prerelease integration.
If a feature should ship in alpha only, merge or retarget that PR to a prerelease branch instead of main.

​
Stable release

Stable releases publish only when a reviewed release/vX.Y.Z PR merges into protected main. Prepare and review release notes before creating the release commit:
On the first run, release:prepare drafts missing changelog artifacts and exits non-zero for review so chained release commands stop before tagging. After the generated TODO summary is rewritten, rerun the same command to create the release commit and tag. See Changelog process for the full workflow. For stable releases, bun run set-version <version> still enforces this checkpoint when maintainers run the lower-level release command directly. Push the release branch without its local tag, open a PR to main, and merge it after approval and CI. The publish workflow checks out the exact PR merge SHA, verifies it before publishing, creates the stable tag at that commit, publishes npm packages, and creates the GitHub release. If that workflow needs recovery, rerun its original merged-PR event. Stable tag pushes and manual dispatches do not publish, so recovery cannot select a different commit. For hotfixes, branch from the last stable tag, cherry-pick only the fix, publish the patch release, then merge or cherry-pick the same fix back into the prerelease branch.

​
Alpha release

Alpha releases must be reachable from a prerelease branch such as origin/next or origin/alpha. Use the same changelog draft workflow when the prerelease contains changes that users should know about.
Consumers can install alpha builds explicitly:

​
CI guardrails

The publish workflow validates release channel boundaries before publishing:
  • Stable versions must publish with latest.
  • Prerelease versions must publish with the prerelease dist-tag, such as alpha.
  • Stable releases must come from a merged, reviewed release/vX.Y.Z PR.
  • Prerelease tags must be reachable from a prerelease branch.
  • Merged release/vX.Y.Z PRs publish stable releases only.
  • Every publish job verifies that its checkout matches the immutable event SHA.
This prevents an alpha-only feature from being included in a stable hotfix by accident.