> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperframes-zh.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 变更日志流程

> HyperFrames 如何起草、审查和发布发行说明。

HyperFrames 变更日志有两个受众：

* 开发人员阅读文档变更日志以了解面向用户的更改、迁移说明以及升级原因。
* 维护者在 npm 发布过程中发布 GitHub 版本。

发布工作流程使双方观众保持同步，同时保留人工编辑步骤。

## 目标

* 使每个稳定版本都易于从文档站点扫描。
* 发布有用的 GitHub 发行说明，而无需仅依赖原始提交日志。
* 在发布之前保持发行说明可编辑。
* 避免过度记录不会改变用户行为的内部提交。

## 真相来源

每个经过审核的发行说明都位于 `releases/vX.Y.Z.md` 中。

文档变更日志位于 `docs/changelog.mdx` 中并使用 Mintlify `<Update>` 条目。草稿生成器可以在前面添加文档条目，但维护人员应在标记版本之前编辑生成的副本。进行任何手动重写后，请保持 `releases/vX.Y.Z.md` 和匹配的文档 `<Update>` 条目同步。

## 稳定的发布流程

<Steps>
  <Step title="准备发布">
    从存储库根目录运行稳定版本命令：

    ```bash theme={null}
    bun run release:prepare 0.6.53
    ```

    第一次运行时，这会创建或更新变更日志草稿，然后在标记之前退出：

    * `releases/v0.6.53.md`
    * `docs/changelog.mdx`

    检查点故意以非零值退出，因此链式释放命令停止。查看生成的副本，删除 TODO 摘要标记，然后重新运行相同的命令。一旦审查了两个变更日志工件，`release:prepare` 就会运行 `set-version` 来创建发布提交和标签。
  </Step>

  <Step title="审查并重写">
    阅读生成的注释并为用户重写它们。优先考虑影响而不是实施细节。

    大喊：

    * 重大变更和所需的迁移步骤
    * 新功能
    * 重要错误修复
    * 性能或可靠性改进
    * 安全修复
  </Step>

  <Step title="重新运行释放命令">
    检查后，再次运行相同的命令：

    ```bash theme={null}
    bun run release:prepare 0.6.53
    ```

    对于稳定版本，`release:prepare` 检查 `releases/v0.6.53.md` 是否存在，`docs/changelog.mdx` 是否具有匹配的 `HyperFrames v0.6.53` 条目，以及两个工件是否仍包含生成的 TODO 摘要。较低级别的 `set-version` 命令为直接运行该命令的维护人员强制执行相同的已审查变更日志检查点。预发布和 `--no-tag` 版本升级会跳过此检查。仅将 `--skip-changelog-check` 用于紧急稳定版本。

    发布提交可以包括版本提升、`releases/v0.6.53.md` 和文档变更日志更新。
  </Step>

  <Step title="发布">
    推送发布标签：

    ```bash theme={null}
    git push origin main --tags
    ```

    当文件存在时，发布工作流程使用 `releases/v0.6.53.md` 作为 GitHub 发布正文。如果不存在已审核的发布文件，则会回退到 GitHub 生成的注释。

    生成的比较链接指向未来的 `v0.6.53` 标记。 PR 合并和最终标签推送之间可能无法解决。
  </Step>
</Steps>

## 草案再生

当您需要在审阅之前重新生成变更日志副本时，请使用较低级别的草稿命令：

```bash theme={null}
bun run changelog:draft 0.6.53 --write --force
```

如果没有 `--force`，草稿命令将保留现有 `releases/vX.Y.Z.md` 文件不变，并且仍然添加文档更改日志条目（如果丢失）。如果文档更改日志已有该版本，请手动编辑现有文档条目。

## 每周摘要工作流程

每周更新是编辑汇总，而不是发行说明。保持 `docs/changelog.mdx` 版本并使用 `docs/weekly-updates.mdx` 来策划每周亮点，这些亮点也可以适用于 Discord 和 X。

从存储库根生成可编辑的每周数据包：

```bash theme={null}
bun run changelog:weekly --from 2026-06-01 --to 2026-06-07 --write
```

从最新的 `main` 分支运行它，以便所选范围反映公共历史记录，而不是功能分支。

这将创建：

* `updates/weekly/2026-06-07.md`
* `updates/social/2026-06-07.discord.md`
* `updates/social/2026-06-07.x.md`

它还在 `docs/weekly-updates.mdx` 前面添加一个匹配条目。在发布之前检查并重写生成的文件。社交草稿永远不会自动发布。

## 写作风格

使用简单、面向用户的语言。与“在渲染活动中添加飞行前检查”相比，更喜欢“修复缺少 FFmpeg 时的 Studio 渲染失败”。当相关文档、迁移指南或拉取请求帮助用户采取行动时，链接到它们。

适用时按此顺序进行团体变更：

1. 重大变化
2. 特征
3. 修复
4. 表现
5. 文档和示例
6. 目录
7. 内部的

避免列出发布提交、仅依赖项更新、生成的文件改动以及标记为 `skip-changelog` 的更改。