mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:00:07 +00:00
* ci(publish): publish prebuilt tarballs from a job that runs no release-commit code Builds, lifecycle scripts and packing move to a pack job with a read-only token and no secrets. The publish job, which holds the npm token and the write token, checks each tarball's name and version against the release and uploads it with lifecycle scripts off. A version already on npm with other contents fails the first attempt instead of being skipped. * ci(publish): prerelease tag pushes publish only after a maintainer approves A prerelease tag can come from any prerelease branch, which no PR review covers. Tag-push runs now use the npm-prerelease environment, which requires a maintainer's approval. Merged release PRs keep the npm-publish environment. * ci(publish): keep every publish in the approval-gated npm-publish environment npm's trusted publishers are pinned to npm-publish, and that environment now requires a maintainer's approval with self-review prevented. A second environment would fail npm auth, so the workflow keeps npm-publish for every trigger. The docs and test name it as the approval gate.
78 lines
4.3 KiB
Plaintext
78 lines
4.3 KiB
Plaintext
---
|
|
title: Release channels
|
|
description: How HyperFrames keeps alpha-only work out of stable releases.
|
|
---
|
|
|
|
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:
|
|
|
|
```bash
|
|
bun run release:prepare <version>
|
|
```
|
|
|
|
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](/contributing/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. Before it publishes, the run waits for a maintainer to approve it in the `npm-publish` environment.
|
|
|
|
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.
|
|
|
|
```bash
|
|
git checkout next
|
|
bun run set-version 0.4.25-alpha.1
|
|
git push origin next
|
|
git push origin v0.4.25-alpha.1
|
|
```
|
|
|
|
The tag push starts the publish workflow. It builds and packs the release, then waits for approval in the `npm-publish` environment. A maintainer other than the person who pushed the tag approves the run on the workflow page, and only then is anything published. A prerelease branch has no PR review, so this approval is its review.
|
|
|
|
Consumers can install alpha builds explicitly:
|
|
|
|
```bash
|
|
npm install hyperframes@alpha
|
|
npm install @hyperframes/core@alpha
|
|
```
|
|
|
|
## 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.
|
|
- Every publish, stable or prerelease, waits for a maintainer other than the one who started it to approve the run in the `npm-publish` environment.
|
|
- Merged `release/vX.Y.Z` PRs publish stable releases only.
|
|
- Every publish job verifies that its checkout matches the immutable event SHA.
|
|
- Builds, lifecycle scripts and `npm pack` run in a job with a read-only token and no secrets.
|
|
- The job that holds the npm token runs no code from the release commit. It checks that every packed tarball is a package this workflow publishes, at exactly the release version, then uploads it with lifecycle scripts off.
|
|
- A version already on npm is skipped only when its contents match the new tarball, or on a re-run of the same workflow run. Otherwise the publish fails, because something other than this run published that version.
|
|
|
|
This prevents an alpha-only feature from being included in a stable hotfix by accident.
|