assemble-changelog

Assemble-changelog

为 Rerun 仓库汇编发布时的变更日志。

始终在独立的 rerun-io/rerun 检出仓库根目录中操作——通常是 prepare-release-0.x.y 分支，并在此提交结果。 这是 RELEASES.md 中的第 4 步；请阅读该文件了解相关背景。

开始任何发布工作之前，请确认当前目录是仓库根目录，且其 origin 为 rerun-io/rerun：

test "$(git rev-parse --show-toplevel)" = "$PWD"
git remote get-url origin

请勿在 reality 单体仓库中运行此工作流，包括在其 rerun/ 目录中运行。 发布脚本需要独立仓库的 0.x.y 标签，并会根据 rerun-io/rerun 解析 (#N) 提交引用。 在 reality 中运行脚本可能会悄无声息地将 reality 的 PR 编号解析为无关的 Rerun PR。

如果任一前提不满足，请在运行任何发布命令前停止。 告知用户此技能要求在独立 rerun-io/rerun 检出仓库的根目录中运行，并请他们在该目录中重新启动。 不要替用户克隆仓库、获取标签或切换分支。

从 $ARGUMENTS 中解析目标版本（例如 0.34.0）。若未提供，请从 Cargo.toml 读取版本（version = "0.x.y-…"），并向用户确认。

工作流

1. 将 upcoming/ 汇编为发布变更集

经过整理的条目按每个 PR 一个文件，存放于 docs/content/changelog/upcoming/*.md （跳过 _template.md）。每个文件都在 frontmatter 中声明 type: highlight|misc|breaking|feature。将它们合并到 docs/content/changelog/changeset-0-XX.md；如果该文件尚不存在，请从 docs/content/changelog/_template.md 创建（将 title 设为版本号——保留引号，例如 title: "0.36"，以便 YAML 将其视为字符串——并将 order 设为比上一版低一位）：

• highlight → 在 ## Highlights 下各写一个 ### 小节。
• feature → 在 ## New features 下各写一个 ### 小节。
• misc → 在 ## Other 下每项恰好写一个 - 列表项。将其 ### 标题和正文合并到该列表项中，并保留链接。不要在列表项之外使用标题或正文。
• breaking → 在 ## Breaking changes 下各写一个 ### 小节。如果没有，则写 None.。

保持这些章节按上述顺序排列；如果没有条目，则省略 Highlights 和 Other。 变更日志面向用户（是网站内容的一部分），因此应首先介绍新增内容； 详尽且仅面向开发者的破坏性变更迁移指南放在最后，让大多数读者不必滚动浏览它们。

根据发布类型调整输出：

• 补丁版本（0.x.Y，Y > 0）→ 通常仅包含错误修复。跳过 Highlights 和 New features（通常不会有 upcoming/ 条目）；仅在有杂项条目时包含 Other，仅在有破坏性变更时保留 Breaking changes。
• 次要版本（0.X.0）→ 使用完整模板：highlights、新功能、其他条目、破坏性变更。

保留每个条目的正文和结构（迁移指南、表格、snippet: 指令、截图、链接），但每个杂项条目需合并为单个列表项。 去除每个条目的 frontmatter。 消除重叠条目，并按影响从大到小排列破坏性变更。

条目中的相对文档链接是以 changelog/ 为基准编写的（例如 ../reference/migration/...），合并后仍然适用——保持原样。

图片和视频必须托管在 static.rerun.io 上（使用 scripts/upload_image.py 上传），不得使用 GitHub 附件：上传到私有单体仓库的附件无法在网站上显示。

功能负责人会按 PR 编写 ## Highlights 条目，因此请通读整个章节，并向负责人员指出任何不连贯之处，而不要自行改写。

最后，将 docs/content/changelog.md 中的 redirect: frontmatter 指向 changelog/changeset-0-XX：CI 的 scripts/ci/check_changelog_redirect.py 要求最新变更集成为重定向目标，因此重定向更新必须与新变更集一同提交。

2. 解决发布阻碍项

确保 upcoming/ 中的所有非模板文件都已合并到变更集，然后在整理好的变更集中搜索未解决的占位符：

rg -n 'TODO\([^)]+\)' docs/content/changelog/changeset-0-XX.md # NOLINT

继续之前，先解决所有匹配项。 未解决的 TODO(name) 会阻碍发布。

3. 生成摘要和详情部分并写入 CHANGELOG.md

pixi run uvpy scripts/generate_changelog.py --version 0.x.y

编辑 PR 标题和标签以改善输出，然后将结果复制到 CHANGELOG.md （删掉末尾的“Chronological changes”部分；像之前的版本一样替换占位的视频／博客文章 行）。抽查几条内容，对照实际的 PR 核实： 标题不符（旧的、不相关的 PR；核心团队成员的 thanks @…）意味着 PR 编号 查找出了问题——请参阅顶部的警告。 检查生成的部分，确认贡献者归属没有错误，也没有拼写错误。 如果发布时不包含 Rust crates（publish-crates=false），请在 CHANGELOG.md 部分说明此版本未发布到 crates.io。

此操作要在步骤 1 之后执行：脚本会读取整理好的变更集并生成其摘要（章节标题 + 网站上的变更集链接），而不是直接内嵌变更集的文本。 因此，CHANGELOG.md 不会重复变更集内容——如果变更集缺失，脚本会输出未解决的占位符。

4. 润色 CHANGELOG.md 部分

生成的部分只是起点；请手动编辑，让读者更容易找到详情。

• 按影响力排序概览。 先列出最重要的新功能，然后是集成和 API，接着是格式支持、改进，最后是小众或面向开发者的项目。

• 分组并排列详情。 脚本按提交顺序输出各个详情小节（🐍 Python API、🪳 Bug 修复、🌁 Viewer 改进，……）。 在每个小节内，将涉及同一功能的条目放在一起（例如，所有 MCP/ViewerControl 条目、所有状态时间线条目、所有卡顿和死锁条目），按组中影响最大的条目排列各组，再按影响力排列组内条目。 只调整行的顺序；不要在小节之间移动条目，也不要删掉条目。

• 为条目添加可点击链接。 在可能的情况下，将概览和详情中的条目链接到展示如何使用该功能的文档：操作指南、原型／视图参考页、CLI 或 MCP 参考部分、Python/JS 参考站点或 docs.rs。 重用变更集已有的链接，并将其转换为 https://rerun.io/docs/<不含 .md 的路径>；检查每个目标文件和 #anchor 标题是否存在。 外部名称也要添加链接（例如第三方工具的文档）。 在详情条目中，只链接关键术语，不要链接整行，这样末尾的提交／PR 链接才会保持独立。

• 为每项破坏性变更添加链接，指向变更集中的对应小标题：https://rerun.io/docs/changelog/changeset-0-XX#<anchor>。 锚点是小标题转换为小写、去掉反引号和标点，并将空格替换为连字符后的结果（rrd::optimize → rrdoptimize）。

• 指出实际的破坏性变更。 变更集和 CHANGELOG.md 中的破坏性变更标题都必须说明破坏了什么，例如“移除 WriteChunks”，而不是替代它的新功能（“Catalog staging”）。 小节开头应先写移除项及迁移指南链接，再介绍替代方案。

• 标明实验性和不稳定功能。 对照以下标记，检查变更集和 CHANGELOG.md 中的每项新功能（PREV 是上一个次要版本的标签，例如 0.38.0）：

  # Non-blueprint types marked unstable whose definitions changed this cycle
  git diff --name-only $PREV HEAD -- crates/build/re_type_definitions | grep -v /blueprint/ | xargs rg -l 'state = "unstable"'
  # Python APIs in the `rerun.experimental` module
  git log --oneline $PREV..HEAD -- rerun_py/rerun_sdk/rerun/experimental
  # Viewer features behind a flag in `ExperimentalAppOptions`
  git diff $PREV HEAD -- crates/viewer_support/re_viewer_context/src/app_options.rs
  # Docs and docstrings that call something experimental
  git diff --name-only $PREV HEAD -- docs/content rerun_py/rerun_sdk | xargs rg -l -i 'is experimental'
  

  在第一条命令中出现某个文件，并不意味着该类型是新的：请将命中的结果与实际条目交叉核对。 对每项符合条件的功能，都要在读者能看到的地方说明：在变更集标题前加上“Experimental”（就像 0.36 中的 ### Experimental 3D gaussian splat support 一样），并添加一句说明它可能会在未来版本中改变（对于不稳定类型，还要说明数据可能无法保持向后兼容）。 如果该功能由标志控制，请说明如何启用。 在 CHANGELOG.md 概览中，将所有这些条目移到“Overview & highlights”末尾新增的 #### 🧪 Experimental and unstable 小节中，并加上一行说明：这些内容可能会改变，且不稳定类型可能无法保持向后兼容。 该小节中的条目也要按影响排序，条目中不要重复写“Experimental”。 Blueprint 类型（re_type_definitions/rerun/blueprint/ 下的 rerun.blueprint.*）是个例外：它们都标记为不稳定，这仅表示 blueprint 数据不向后兼容。 仅此并不意味着某项功能属于实验性功能，因此，只有在其他标记适用于该功能（或它所展示的数据原型）时，新的视图或 blueprint 设置才属于实验性功能。 同样，Viewer 功能不会仅仅因为通过实验性 API 配置就变成实验性功能。

• 为概览中的重点功能添加媒体：在项目符号下方缩进添加屏幕截图（或视频静帧及其链接），并使用 pixi run upload-image 输出的 <picture> 标记。 目标是添加几张图片（大约 3 到 5 张），涵盖最具视觉效果的重点功能：图片展示新的视图或渲染器功能，远比项目符号更直观。 优先使用变更集和 PR 描述中已有的媒体；如果某项视觉功能没有媒体，请向用户索要截图，而不是跳过。 不要为每个条目都添加图片：API、CLI 和错误修复条目通常不适合添加。 所有媒体都必须托管在 static.rerun.io 上。 只有当 PR 中的媒体已托管在 static.rerun.io 或可公开访问时，才能复用。私有 monorepo 中的 github.com/user-attachments/… 链接对外部访问会返回 404。 使用 curl -L -H "Authorization: token $(gh auth token)" <url> 下载这些文件，然后用 pixi run upload-image <file> --name <name> 上传。 GitHub 不会渲染来自外部主机的 <video>，因此对于视频，请提取一帧具有代表性的静帧（ffmpeg -ss <t> -i video.mp4 -frames:v 1 still.png），上传该图片，并在其下方链接 .mp4 文件。 查看视频帧并选择主体上没有光标遮挡的一帧。

5. 清空收件箱

删除已合并的 upcoming/*.md 条目，保留 _template.md 和本次发布未包含的条目。 绝不要为这些临时条目添加重定向。

宣布完成前的检查清单

• upcoming/ 中每个非模板条目都已纳入变更集。
• 变更集中没有遗留任何 TODO(name)。
• 没有为现有条目编造摘要或其他说明文字。
• CHANGELOG.md 概览按影响排序，其中几个最具视觉效果的重点功能配有 static.rerun.io 图片，且破坏性变更链接到了变更集中的对应小标题。
• 每个概览和详情条目都已链接到相关文档（如有）。
• 详情中的每个小节都按功能对条目分组，并将影响最大的条目排在最前面。
• 每个实验性或不稳定功能（功能标志、rerun.experimental、非 blueprint 类型上的 #[rerun(state = "unstable")]，或文档标注为实验性）都已在变更集中标注，并列入概览最后的“实验性和不稳定功能”小节。
• pixi run lint-rerun CHANGELOG.md docs/content/changelog/changeset-0-XX.md 检查通过。
• 图片和视频托管在 static.rerun.io，而非作为 GitHub 附件。
• 整体而言，## Highlights 易于阅读；如果并非如此，已告知人工审核者具体问题。
• CHANGELOG.md 小节中的贡献者署名正确，且没有拼写错误。
• upcoming/ 仅包含 _template.md 和延期至后续版本的条目。
• python scripts/ci/check_changelog_redirect.py 检查通过（重定向指向此变更集）。
• python scripts/ci/check_doc_redirects.py --base origin/main 检查通过（upcoming/ 条目不受检查，且无需重定向）。

说明

• 此技能位于独立 Rerun 仓库的 skills/assemble-changelog 中。
• rerun-io/rerun 中同步的提交带有 Source-Ref trailer（即 reality 合并提交）；generate_changelog.py 会追溯到原始 reality PR，以获取正确的标题、标签和贡献者信息。
• 不会预先创建下一个版本的变更集：未发布版本的空变更集会导致 check_changelog_redirect.py 检查失败，因为该脚本要求最新的 changeset-0-xx.md 是重定向目标。在一个发布周期中，upcoming/ 是唯一进行中的产物。