prepare-release-notes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Prepare Release Notes

准备发布说明

Polish pending React Router change files and add manual release notes only when the release needs narrative context beyond the generated change lists.

润色待处理的 React Router 变更文件，仅当发布需要超出自动生成变更列表的叙述性说明时，才添加手动编写的发布说明。

Workflow

工作流

Inspect local state:

git status --short
find packages -path '*/.changes/*.md' -not -name README.md -not -name .gitkeep -print | sort

Read every pending change file. Do not edit generated changelogs or released notes directly.
Normalize each change file:
- Remove
```
feat:
```
  ,
```
feat(...)
```
  ,
```
fix:
```
  , and
```
fix(...)
```
  semantic-commit prefixes from prose
- Use present or imperative tense for the first line and top-level release bullets: prefer
```
Add
```
  ,
```
Fix
```
  ,
```
Remove
```
  ,
```
Support
```
  ,
```
Stabilize
```
  ,
```
Preserve
```
  ,
```
Update
```
  ,
```
Avoid
```
  ,
```
Prevent
```
  ,
```
Throw
```
  ,
```
Warn
```
  ,
```
Expose
```
- Nested detail bullets can stay explanatory when they expand on the parent bullet; do not rewrite them solely to force present or imperative tense
- Remove terminal sentence periods from bullet items because release generation appends PR/commit links after the first bullet line
- Remove terminal sentence periods from nested bullet items too, unless the punctuation is part of code, a URL, an abbreviation, a version number, or another token where removing it would be wrong
- If one bullet contains multiple sentences, split it into a shorter parent bullet plus nested bullet items
- Keep the first line concise and user-facing; use nested bullets for details or migration notes
Review whether
```
scripts/changes/whats-changed.md
```
is needed:
- Read
```
CHANGELOG.md
```
  examples or
```
references/whats-changed.md
```
  when uncertain
- Add
```
scripts/changes/whats-changed.md
```
  only for features, future flag stabilizations, unstable flags, migration guidance, breaking bug fixes, or complex behavior that needs long-form text or examples
- Do not add it for ordinary bug fixes, dependency cleanup, internal refactors, or release bullets that are already clear
- If adding it, write the body only; the release script adds
```
### What's Changed
```
  when missing
Validate:

pnpm changes:validate
pnpm changes:preview

Use

changes:preview

to inspect the generated root release notes and confirm the PR/commit link placement, section ordering, and any manual What's Changed placement. If dependencies are missing or the command is too expensive for the context, state what was skipped.

检查本地状态：

git status --short
find packages -path '*/.changes/*.md' -not -name README.md -not -name .gitkeep -print | sort

阅读所有待处理的变更文件。不要直接编辑自动生成的变更日志或已发布的说明。
规范化每个变更文件：
- 从正文中移除
```
feat:
```
  、
```
feat(...)
```
  、
```
fix:
```
  和
```
fix(...)
```
  等语义化提交前缀
- 首行和顶层发布条目使用现在时或祈使语气：优先使用
```
Add
```
  、
```
Fix
```
  、
```
Remove
```
  、
```
Support
```
  、
```
Stabilize
```
  、
```
Preserve
```
  、
```
Update
```
  、
```
Avoid
```
  、
```
Prevent
```
  、
```
Throw
```
  、
```
Warn
```
  、
```
Expose
```
  等动词
- 嵌套的细节条目如果是对父条目的补充说明，可以保持原有语气；不要仅仅为了强制使用现在时或祈使语气而重写它们
- 移除条目的句末句号，因为发布生成脚本会在第一条目行后追加 PR/提交链接
- 嵌套条目也要移除句末句号，除非该标点是代码、URL、缩写、版本号或其他移除后会出错的标记的一部分
- 如果一个条目包含多个句子，将其拆分为更简短的父条目加嵌套子条目
- 保持首行简洁且面向用户；使用嵌套条目存放细节或迁移说明
检查是否需要添加
```
scripts/changes/whats-changed.md
```
：
- 不确定时可阅读
```
CHANGELOG.md
```
  示例或
```
references/whats-changed.md
```
- 仅当涉及功能、未来特性标志稳定化、不稳定标志、迁移指南、破坏性 bug 修复，或需要长文本或示例说明的复杂行为时，才添加
```
scripts/changes/whats-changed.md
```
- 普通 bug 修复、依赖清理、内部重构或已经清晰的发布条目不需要添加
- 如果添加该文件，只需编写正文；发布脚本会在缺少
```
### What's Changed
```
  标题时自动添加
验证：

pnpm changes:validate
pnpm changes:preview

使用

changes:preview

检查生成的根目录发布说明，确认 PR/提交链接的位置、章节顺序以及所有手动添加的「变更说明」的位置。如果缺少依赖或该命令在当前场景下成本过高，请说明跳过的内容。

Change File Style

变更文件风格

Single-line entries should read well with an auto-appended PR link:

markdown

Fix `href()` to stringify and URL-encode param values like `generatePath()`

Use nested bullets for additional sentences:

markdown

Fix route ranking for dynamic parameters with static extension suffixes

- Identify `/:name.xml` as a dynamic segment instead of a static segment
- Preserve static route priority for paths like `/sitemap.xml`

Avoid semantic commit prefixes:

markdown

Add support for nub as a package manager

not:

markdown

feat: add support for nub as a package manager.

单行条目在自动追加 PR 链接后应读起来通顺：

markdown

Fix `href()` to stringify and URL-encode param values like `generatePath()`

额外的句子使用嵌套条目：

markdown

Fix route ranking for dynamic parameters with static extension suffixes

- Identify `/:name.xml` as a dynamic segment instead of a static segment
- Preserve static route priority for paths like `/sitemap.xml`

避免使用语义化提交前缀：

markdown

Add support for nub as a package manager

错误示例：

markdown

feat: add support for nub as a package manager.

What's Changed Guidance

「变更说明」编写指南

Use

scripts/changes/whats-changed.md

for release-level narrative, not package-specific bullets. Good candidates include:

A new user-facing API or feature that benefits from example code
Stabilization or renaming of unstable APIs/flags, especially when adopters must migrate
A stable future flag that changes behavior and needs adoption guidance
A breaking bug fix or adapter/runtime behavior change that may require deployment checks
A cluster of related changes whose combined effect matters more than the individual bullet list

Keep the tone direct and practical. Prefer headings under the generated

### What's Changed

section:

markdown

undefined

scripts/changes/whats-changed.md

用于发布层面的叙述，而非特定包的条目。适用场景包括：

配有示例代码更易理解的新用户侧 API 或功能
不稳定 API/标志的稳定化或重命名，尤其是需要使用者进行迁移的情况
会改变行为且需要采用指南的稳定未来特性标志
可能需要部署检查的破坏性 bug 修复或适配器/运行时行为变更
一组相关变更，其整体影响比单个条目列表更重要

保持语气直接、务实。优先在自动生成的

### What's Changed

章节下使用子标题：

markdown

undefined

Feature Name

Explain what changed, who it affects, and how to adopt it.

// Optional short example


Do not duplicate every bullet from Minor/Patch/Unstable Changes. Let generated change files carry ordinary PR-level details.

See `references/whats-changed.md` for examples distilled from the existing changelog.

Explain what changed, who it affects, and how to adopt it.

// Optional short example


不要重复次要/补丁/不稳定变更中的每一个条目。让自动生成的变更文件承载普通的 PR 级别细节。

参考 `references/whats-changed.md` 可查看从现有变更日志中提炼的示例。