mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-17 15:24:19 +00:00
* feat(docs): add changelog release workflow * fix(scripts): resolve CodeQL findings in release scripts - draft-changelog.ts: replace existsSync+writeFileSync check-then-act with an atomic exclusive-write flag (flag: wx) to fix the js/file-system-race TOCTOU finding; overwrite only under --force (flag: w). - set-version.ts: switch execSync shell-string git calls to execFileSync with argument arrays so the interpolated version/paths can never be interpreted by a shell, resolving the js/indirect-command-line-injection findings. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(scripts): lower writeReleaseNotes complexity below CRAP threshold The exclusive-write fix pushed writeReleaseNotes to cyclomatic 5 / CRAP 30.0 (fallow/high-crap-score, threshold 30.0). The '!force' guard in the catch is redundant — EEXIST is only reachable under the 'wx' flag (force=false), since 'w' overwrites without throwing. Dropping it returns the function to cyclomatic 4 / CRAP 20 with identical behavior. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(docs): address changelog review feedback --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
85 lines
3.4 KiB
Plaintext
85 lines
3.4 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.
|
|
|
|
## Release note workflow
|
|
|
|
<Steps>
|
|
<Step title="Draft the release notes">
|
|
Run the draft command from the repository root:
|
|
```bash
|
|
bun run changelog:draft 0.6.53 --write
|
|
```
|
|
This creates or updates:
|
|
- `releases/v0.6.53.md`
|
|
- `docs/changelog.mdx`
|
|
|
|
Use `--force` only when regenerating a draft before review. It overwrites `releases/vX.Y.Z.md`; if the docs changelog already has that version, edit the existing docs entry manually.
|
|
</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="Create the release commit">
|
|
Run the existing fixed-version release command:
|
|
```bash
|
|
bun run set-version 0.6.53
|
|
```
|
|
For stable releases, `set-version` checks that `releases/v0.6.53.md` exists and that `docs/changelog.mdx` has a matching `HyperFrames v0.6.53` entry before it updates package versions or creates the tag. 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>
|
|
|
|
## 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`.
|