Skip to main content
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

1

Prepare the release

Run the stable release command from the repository root:
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.
2

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
3

Rerun the release command

After review, run the same command again:
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.
4

Publish

Push the release tag:
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.

​
Draft regeneration

Use the lower-level draft command when you need to regenerate changelog copy before review: 
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.

​
Weekly digest workflow

Weekly updates are editorial rollups, not release notes. Keep docs/changelog.mdx versioned and use docs/weekly-updates.mdx for curated weekly highlights that can also be adapted for Discord and X. Generate an editable weekly packet from the repository root: 
bun run changelog:weekly --from 2026-06-01 --to 2026-06-07 --write
Run it from an up-to-date main branch so the selected range reflects public history, not a feature branch. This creates:
  • updates/weekly/2026-06-07.md
  • updates/social/2026-06-07.discord.md
  • updates/social/2026-06-07.x.md
It also prepends a matching entry to docs/weekly-updates.mdx. Review and rewrite the generated files before publishing. Social drafts are never posted automatically.

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