mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-01 19:42:03 +00:00
James Russo
17b0db1d3e
## What - Add `bun run release:prepare <version>` as the maintainer-facing stable release entrypoint. - Make the first run draft missing changelog artifacts and intentionally exit before tagging; rerunning after manual review delegates to `set-version`. - Tighten the direct `set-version` guard so stable releases also fail when generated TODO changelog copy is still present. - Update maintainer docs to recommend `release:prepare` while keeping `changelog:draft` as the lower-level regeneration tool. ## Why Stable releases should be hard to run without reviewed GitHub release notes and Mintlify changelog copy. This keeps the existing manual rewrite step, but makes the expected path one command that engineers can rerun after review. ## How - Added `scripts/release-prepare.ts` with parsing, draft/review/set-version action selection, and command forwarding. - Added focused script tests for parser behavior, action selection, command forwarding, and TODO detection. - Extracted shared script CLI parsing helpers so `changelog:draft` and `release:prepare` use the same option handling. - Adjusted `changelog:draft --write` so an existing release file is left unchanged unless `--force` is passed, while still allowing a missing docs entry to be added. ## Test plan - [x] Unit tests added/updated: `bun run test:scripts` - [x] Format check: `bun run format:check` - [x] Lint: `bun run lint` - [x] Typecheck: `bun run --filter '*' typecheck` - [x] Fallow audit: `bunx fallow audit --base origin/main --fail-on-issues` - [x] Manual CLI checks: `bun run release:prepare --help`; `bun run set-version 9.9.9` fails before mutation when changelog artifacts are missing - [x] Documentation updated
72 lines
2.8 KiB
Plaintext
72 lines
2.8 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 must be reachable from `origin/main` or `origin/release/v*`.
|
|
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.
|
|
|
|
```bash
|
|
bun run release:prepare <version>
|
|
git push origin main --tags
|
|
```
|
|
|
|
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
|
|
```
|
|
|
|
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 tags must be reachable from `main` or `release/v*`.
|
|
- Prerelease tags must be reachable from a prerelease branch.
|
|
- Merged `release/vX.Y.Z` PRs publish stable releases only.
|
|
|
|
This prevents an alpha-only feature from being included in a stable hotfix by accident.
|