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

## 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:

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

<Warning>
  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.
</Warning>

Review and rewrite all four before publishing anything. Social drafts are never posted automatically. Exact versioned release notes stay in the [Changelog](/changelog); [Weekly updates](/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`.
