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

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

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