> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes-feat-media-use-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog process

> 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 theme={null}
    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 theme={null}
    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 theme={null}
    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 theme={null}
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 theme={null}
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`.