mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-14 18:01:20 +08: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
95 lines
4.1 KiB
Plaintext
95 lines
4.1 KiB
Plaintext
---
|
|
title: Changelog process
|
|
description: How HyperFrames drafts, reviews, and publishes release notes.
|
|
---
|
|
|
|
HyperFrames changelogs have two audiences:
|
|
|
|
- Developers reading the docs changelog for user-facing changes, migration notes, and reasons to upgrade.
|
|
- Maintainers publishing GitHub Releases during the npm release process.
|
|
|
|
The release workflow keeps both audiences in sync while preserving a human editing step.
|
|
|
|
## Goals
|
|
|
|
- Make every stable release easy to scan from the docs site.
|
|
- Publish useful GitHub Release notes without relying only on raw commit logs.
|
|
- Keep release notes editable before publishing.
|
|
- Avoid over-documenting internal-only commits that do not change user behavior.
|
|
|
|
## Source of truth
|
|
|
|
Each reviewed release note lives in `releases/vX.Y.Z.md`.
|
|
|
|
The docs changelog lives in `docs/changelog.mdx` and uses Mintlify `<Update>` entries. The draft generator can prepend a docs entry, but maintainers should edit the generated copy before tagging the release. After any manual rewrite, keep `releases/vX.Y.Z.md` and the matching docs `<Update>` entry in sync.
|
|
|
|
## Stable release workflow
|
|
|
|
<Steps>
|
|
<Step title="Prepare the release">
|
|
Run the stable release command from the repository root:
|
|
```bash
|
|
bun run release:prepare 0.6.53
|
|
```
|
|
On the first run, this creates or updates the changelog draft and then exits before tagging:
|
|
- `releases/v0.6.53.md`
|
|
- `docs/changelog.mdx`
|
|
|
|
The checkpoint exits non-zero intentionally so chained release commands stop. Review the generated copy, remove the TODO summary marker, and rerun the same command. Once both changelog artifacts are reviewed, `release:prepare` runs `set-version` to create the release commit and tag.
|
|
</Step>
|
|
<Step title="Review and rewrite">
|
|
Read the generated notes and rewrite them for users. Prioritize impact over implementation detail.
|
|
|
|
Call out:
|
|
- Breaking changes and required migration steps
|
|
- New capabilities
|
|
- Important bug fixes
|
|
- Performance or reliability improvements
|
|
- Security fixes
|
|
</Step>
|
|
<Step title="Rerun the release command">
|
|
After review, run the same command again:
|
|
```bash
|
|
bun run release:prepare 0.6.53
|
|
```
|
|
For stable releases, `release:prepare` checks that `releases/v0.6.53.md` exists, that `docs/changelog.mdx` has a matching `HyperFrames v0.6.53` entry, and that neither artifact still contains the generated TODO summary. The lower-level `set-version` command enforces the same reviewed-changelog checkpoint for maintainers who run it directly. Prereleases and `--no-tag` version bumps skip this check. Use `--skip-changelog-check` only for emergency stable releases.
|
|
|
|
The release commit can include the version bump, `releases/v0.6.53.md`, and the docs changelog update.
|
|
</Step>
|
|
<Step title="Publish">
|
|
Push the release tag:
|
|
```bash
|
|
git push origin main --tags
|
|
```
|
|
The publish workflow uses `releases/v0.6.53.md` as the GitHub Release body when the file exists. If no reviewed release file is present, it falls back to GitHub-generated notes.
|
|
|
|
The generated compare link points to the future `v0.6.53` tag. It may not resolve between the PR merge and the final tag push.
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Draft regeneration
|
|
|
|
Use the lower-level draft command when you need to regenerate changelog copy before review:
|
|
|
|
```bash
|
|
bun run changelog:draft 0.6.53 --write --force
|
|
```
|
|
|
|
Without `--force`, the draft command leaves an existing `releases/vX.Y.Z.md` file unchanged and still adds the docs changelog entry if it is missing. If the docs changelog already has that version, edit the existing docs entry manually.
|
|
|
|
## Writing style
|
|
|
|
Use plain, user-facing language. Prefer "Fixed Studio render failures when FFmpeg is missing" over "Added pre-flight check in render activity." Link to relevant docs, migration guides, or pull requests when they help users act.
|
|
|
|
Group changes in this order when applicable:
|
|
|
|
1. Breaking Changes
|
|
2. Features
|
|
3. Fixes
|
|
4. Performance
|
|
5. Docs & Examples
|
|
6. Catalog
|
|
7. Internal
|
|
|
|
Avoid listing release commits, dependency-only updates, generated file churn, and changes labeled `skip-changelog`.
|