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:
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:
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/v0.6.53 branch without its local tag, open a PR to main, and merge it after approval and CI. The publish workflow pins its checkout to the exact merge SHA, verifies that SHA, creates v0.6.53, and uses releases/v0.6.53.md as the GitHub Release body. If no reviewed release file is present, it falls back to GitHub-generated notes.To recover a failed publish, rerun the original merged-PR workflow. Do not push the stable tag or use a manual dispatch; those paths are intentionally disabled so recovery cannot publish a different commit.The generated compare link points to the future v0.6.53 tag. It may not resolve until the release PR merges and the publish workflow creates the tag.

​
Draft regeneration

Use the lower-level draft command when you need to regenerate changelog copy before review:
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 packets are editorial source material, not a public documentation page. Keep docs/changelog.mdx versioned. Only publish a human-readable product update when there is a real story, an owner, and enough context to help users act. When docs/product-updates.mdx is public, the release owner reviews it during the first stable release of each month. Update it only when several changes form a useful user story; otherwise keep the latest dated edition and confirm that its claims still describe the current product. Remove the page from navigation if no one owns that review. Generate an editable weekly packet from the repository root:
Run it from an up-to-date main branch so the selected range reflects public history, not a feature branch. This writes three internal editorial drafts:
  • updates/weekly/2026-06-07.md
  • updates/social/2026-06-07.discord.md
  • updates/social/2026-06-07.x.md
It also writes a fourth file, and that one is public. --write prepends the generated entry straight into docs/weekly-updates.mdx, which ships in the sidebar under Explore. Review that diff with the same care as the page it is — it is not a draft. Re-running for a range already present is a no-op, so the entry is safe to edit in place afterwards.
Review and rewrite all four before publishing anything. Social drafts are never posted automatically. Exact versioned release notes stay in the Changelog; Weekly updates carries the curated highlights and an RSS feed.

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