prepare-release-notes

准备发布说明

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

工作流

1. 检查本地状态：

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

2. 阅读每个待处理的变更文件。不要直接编辑生成的 changelog 或已发布的说明。

3. 规范化每个变更文件：

   • 从正文中移除 feat:、feat(...)、fix: 和 fix(...) 语义化提交前缀
   • 第一行和顶层发布条目使用现在时或祈使语气：优先使用 Add、Fix、Remove、Support、Stabilize、Preserve、Update、Avoid、Prevent、Throw、Warn、Expose
   • 当嵌套的详情条目是对父条目的展开说明时，可以保持解释性语气；不要仅仅为了强制使用现在时或祈使语气而重写它们
   • 从条目中移除句末句号，因为发布生成会在第一个条目行之后追加 PR/commit 链接
   • 也从嵌套条目中移除句末句号，除非该标点是代码、URL、缩写、版本号或其他标记的一部分，移除它会造成错误
   • 如果一个条目包含多个句子，将其拆分为一个更短的父条目加上嵌套条目
   • 保持第一行简洁且面向用户；使用嵌套条目来承载细节或迁移说明

4. 审查是否需要 scripts/changes/whats-changed.md：

   • 不确定时阅读 CHANGELOG.md 示例或 references/whats-changed.md
   • 仅为以下情况添加 scripts/changes/whats-changed.md：新功能、未来 flag 的稳定化、不稳定的 flag、迁移指南、破坏性 bug 修复，或需要长文或示例的复杂行为
   • 不要为普通 bug 修复、依赖清理、内部重构或已经清晰的发布条目添加它
   • 如果要添加，只写正文；发布脚本会在缺失时添加 ### What's Changed

5. 验证：

pnpm changes:validate
pnpm changes:preview

使用 changes:preview 检查生成的根发布说明，确认 PR/commit 链接的位置、章节顺序以及任何手动 What's Changed 的位置。如果缺少依赖或该命令对当前上下文来说开销太大，说明跳过了什么。

变更文件风格

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

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

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

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`

避免语义化提交前缀：

Add support for nub as a package manager

而不是：

feat: add support for nub as a package manager.

What's Changed 指南

使用 scripts/changes/whats-changed.md 来承载发布级别的叙述，而不是包特定的条目。合适的候选包括：

• 一个面向用户的新 API 或功能，能从示例代码中获益
• 不稳定 API/flag 的稳定化或重命名，尤其是当采用者必须迁移时
• 一个会改变行为的稳定未来 flag，需要采用指南
• 一个破坏性 bug 修复或适配器/运行时行为变更，可能需要部署检查
• 一组相关变更，其组合效果比单个条目列表更重要

保持语气直接且实用。优先使用生成的 ### What's Changed 章节下的标题：

#### Feature Name

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

```ts
// Optional short example
```

不要重复 Minor/Patch/Unstable Changes 中的每一个条目。让生成的变更文件承载普通的 PR 级别细节。

有关从现有 changelog 中提炼的示例，请参阅 references/whats-changed.md。