Files
hyperframes/docs/contributing/changelog-process.mdx
T
James RussoandClaude Opus 4.8 248f640734 feat(docs): add changelog release workflow (#1164)
* 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>
2026-06-02 15:51:16 -07:00

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`.