assemble-changelog

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Assemble-changelog

Release-time changelog assembly for the Rerun repo.

Always work in the root of a standalone

rerun-io/rerun

checkout — normally the

prepare-release-0.x.y

branch, where the result is committed. This is step 4 of RELEASES.md; read it for the surrounding context.

Before doing any release work, verify that the current directory is the repository root and that its

origin

rerun-io/rerun

bash

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

Do not run the workflow in the reality monorepo, including from its

rerun/

directory. The release scripts need the standalone repository's

0.x.y

tags and resolve

(#N)

commit references against

rerun-io/rerun

. Running them against reality can silently resolve reality PR numbers to unrelated Rerun PRs.

If either precondition is not met, stop before running any release command. Tell the user that the skill requires the root of a standalone

rerun-io/rerun

checkout, and ask them to restart it there. Do not clone a repository, fetch tags, or switch branches for the user.

Resolve the target version from

$ARGUMENTS

(e.g.

0.34.0

). If absent, read it from

Cargo.toml

(

version = "0.x.y-…"

) and confirm with the user.

Rerun仓库的版本发布阶段变更日志组装流程。

请始终在独立的

rerun-io/rerun

仓库根目录下操作——通常是

prepare-release-0.x.y

分支，操作结果将提交到该分支。这是RELEASES.md中的第4步；请阅读该文档了解相关背景信息。

在进行任何发布工作之前，请验证当前目录是否为仓库根目录，且

origin

指向

rerun-io/rerun

：

bash

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

）并与用户确认。

Workflow

工作流

1. Assemble

upcoming/

→ the release changeset

1. 将

upcoming/

条目合并为版本变更集

The curated entries live one-file-per-PR in

docs/content/changelog/upcoming/*.md

(skip

_template.md

). Each declares

type: highlight|breaking|feature

in its frontmatter. Merge them into

docs/content/changelog/changeset-0-XX.md

, creating that file from

docs/content/changelog/_template.md

if it does not exist yet (set

title

to the version — keep it quoted, e.g.

title: "0.36"

, so YAML keeps it a string — and

order

one lower than the previous release):

```
highlight
```
→ fold into the
```
## Highlights
```
prose (write a cohesive few sentences selling the release; use the entries as raw material, don't just concatenate).
```
feature
```
→ one
```
### 
```
subsection each under
```
## New features
```
.
```
breaking
```
→ one
```
### 
```
subsection each under
```
## Breaking changes
```
. If none, write
```
None.
```
.

Keep the sections in that order. The changelog is user-facing (it's part of the website), so it leads with what's new; the verbose, developer-only breaking-change migration guides go last so most readers don't have to scroll past them.

Tailor the output to the release type:

Patch release (
```
0.x.Y
```
, Y > 0) → typically only bug fixes. Skip
```
Highlights
```
and
```
New features
```
(there usually won't be
```
upcoming/
```
entries anyway); keep
```
Breaking changes
```
only if there are any.
Minor release (
```
0.X.0
```
) → the full template: highlights, new features, breaking changes.

Preserve each entry's prose and structure (migration guides, tables,

snippet:

directives, screenshots, links). De-duplicate overlapping entries and order breaking changes most-impactful first. Drop the per-entry frontmatter.

Relative doc links in entries were written as if from

changelog/

(e.g.

../reference/migration/...

), which is correct once merged — keep them as-is.

Finally, point the

redirect:

frontmatter in

docs/content/changelog.md

changelog/changeset-0-XX

: CI's

scripts/ci/check_changelog_redirect.py

requires the newest changeset to be the redirect target, so the repoint must land together with the new changeset.

经过整理的条目以每个PR对应一个文件的形式存放在

docs/content/changelog/upcoming/*.md

中（跳过

_template.md

）。每个文件的前置元数据中声明了

type: highlight|breaking|feature

。将这些条目合并到

docs/content/changelog/changeset-0-XX.md

中，如果该文件尚未存在，则从

docs/content/changelog/_template.md

创建（将

title

设置为版本号——保持引号包裹，例如

title: "0.36"

，确保YAML将其识别为字符串——并将

order

设置为比上一个版本小1）：

```
highlight
```
→ 整合到
```
## Highlights
```
章节中（撰写连贯的几句话来介绍版本亮点；以条目为素材，不要简单拼接）。
```
feature
```
→ 在
```
## New features
```
下每个条目对应一个
```
###
```
子章节。
```
breaking
```
→ 在
```
## Breaking changes
```
下每个条目对应一个
```
###
```
子章节。如果没有此类条目，请写入
```
None.
```
。

请保持上述章节顺序。变更日志面向用户（会展示在官网中），因此优先展示新内容；面向开发者的详细破坏性变更迁移指南放在最后，避免大多数读者需要滚动跳过。

根据版本类型调整输出内容：

补丁版本（
```
0.x.Y
```
，Y > 0）→ 通常仅包含Bug修复。跳过
```
Highlights
```
和
```
New features
```
章节（通常
```
upcoming/
```
目录下也不会有对应条目）；仅当存在破坏性变更时保留
```
Breaking changes
```
章节。
次要版本（
```
0.X.0
```
）→ 使用完整模板：包含亮点、新功能、破坏性变更章节。

保留每个条目的文本内容和结构（迁移指南、表格、

snippet:

指令、截图、链接）。去重重叠条目，并按影响程度从高到低排列破坏性变更。删除每个条目的前置元数据。

条目中的相对文档链接是基于

changelog/

目录编写的（例如

../reference/migration/...

），合并后链接依然有效——请保持原样。

最后，将

docs/content/changelog.md

中的

redirect:

前置元数据指向

changelog/changeset-0-XX

：CI的

scripts/ci/check_changelog_redirect.py

要求最新的变更集作为重定向目标，因此重定向设置必须与新变更集一同提交。

2. Resolve release blockers

2. 解决发布阻塞问题

Ensure that every non-template file from

upcoming/

was merged into the changeset, then search the assembled changeset for unresolved placeholders:

bash

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

Resolve every match before continuing. An unresolved

TODO(name)

blocks the release.

确保

upcoming/

目录下所有非模板文件都已合并到变更集中，然后在组装好的变更集中搜索未解决的占位符：

bash

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

继续操作前请解决所有匹配项。未解决的

TODO(name)

会阻塞发布流程。

3. Generate the summary and detail sections into CHANGELOG.md

3. 生成CHANGELOG.md的摘要和详细章节

bash

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

Edit PR titles/labels to improve the output, then copy the result into

CHANGELOG.md

(drop the trailing "Chronological changes" section; replace the placeholder video/blogpost lines as previous releases did). Spot-check a few entries against the actual PRs: polluted titles (old, unrelated PRs;

thanks @…

for core team members) mean a PR-number lookup misfired — see the warning at the top.

Do this after step 1: the script reads the assembled changeset and emits a summary of it (section headings + links to the changeset on the website), rather than inlining its prose.

CHANGELOG.md

therefore never duplicates the changeset — if the changeset is missing, the script emits an unresolved placeholder instead.

bash

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

编辑PR标题/标签以优化输出结果，然后将结果复制到

CHANGELOG.md

中（删除末尾的“Chronological changes”章节；按照之前版本的方式替换占位的视频/博客文章链接）。随机抽查几个条目与实际PR对比：标题混乱（包含旧的、无关的PR；核心团队成员的

thanks @…

内容）意味着PR编号查找出错——请参考顶部的警告信息。

请在步骤1之后执行此操作：该脚本会读取组装好的变更集并生成其摘要（章节标题+指向官网变更集的链接），而非直接嵌入其文本内容。因此

CHANGELOG.md

永远不会与变更集重复内容——如果变更集缺失，脚本会输出未解决的占位符。

4. Empty the inbox

4. 清空待处理目录

Delete the merged

upcoming/*.md

entries, keeping

_template.md

bash

find docs/content/changelog/upcoming -maxdepth 1 -type f -name '*.md' ! -name '_template.md' -exec git rm -- {} +

删除已合并的

upcoming/*.md

条目，保留

_template.md

：

bash

find docs/content/changelog/upcoming -maxdepth 1 -type f -name '*.md' ! -name '_template.md' -exec git rm -- {} +

Checklist before declaring done

完成前检查清单

Every non-template
```
upcoming/
```
entry is represented in the changeset.
No
```
TODO(name)
```
remains in the changeset.
```
## Highlights
```
reads as a coherent whole, not a list of fragments.
```
upcoming/
```
contains only
```
_template.md
```
.

python scripts/ci/check_changelog_redirect.py

passes (redirect points at this changeset).

所有非模板的
```
upcoming/
```
条目都已在变更集中体现。
变更集中无遗留的
```
TODO(name)
```
。
```
## Highlights
```
章节内容连贯，而非片段列表。
```
upcoming/
```
目录下仅保留
```
_template.md
```
。
```
python scripts/ci/check_changelog_redirect.py
```
执行通过（重定向指向当前变更集）。

Notes

注意事项

This skill lives in
```
skills/assemble-changelog
```
in the standalone Rerun repository.
Synced commits in
```
rerun-io/rerun
```
carry a
```
Source-Ref
```
trailer (the reality merge commit);
```
generate_changelog.py
```
resolves it back to the originating reality PR for correct titles, labels, and contributors.
The next release's changeset is not pre-created: an empty changeset for an unreleased version would make
```
check_changelog_redirect.py
```
fail, since it requires the newest
```
changeset-0-xx.md
```
to be the redirect target. During a cycle,
```
upcoming/
```
is the only in-flight artifact.

本技能位于独立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/
```
是唯一的待处理工件。

assemble-changelog

Original

Translation

Assemble-changelog

Assemble-changelog

Workflow

工作流

1. Assemble
`upcoming/`
→ the release changeset

1. 将
`upcoming/`
条目合并为版本变更集

2. Resolve release blockers

2. 解决发布阻塞问题

3. Generate the summary and detail sections into CHANGELOG.md

3. 生成CHANGELOG.md的摘要和详细章节

4. Empty the inbox

4. 清空待处理目录

Checklist before declaring done

完成前检查清单

Notes

注意事项

assemble-changelog

Original

Translation

Assemble-changelog

Assemble-changelog

Workflow

工作流

1. Assemble upcoming/ → the release changeset

1. 将upcoming/条目合并为版本变更集

2. Resolve release blockers

2. 解决发布阻塞问题

3. Generate the summary and detail sections into CHANGELOG.md

3. 生成CHANGELOG.md的摘要和详细章节

4. Empty the inbox

4. 清空待处理目录

Checklist before declaring done

完成前检查清单

Notes

注意事项

1. Assemble
`upcoming/`
→ the release changeset

1. 将
`upcoming/`
条目合并为版本变更集