release-notes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Release notes

发布说明

Goal

目标

Produce accurate, scannable release notes (Markdown) for a specific release range.

为指定的发布区间生成准确、易浏览的Markdown格式发布说明。

Inputs to ask for (if missing)

需确认的输入信息（若缺失）

Release version + date (or "unreleased").
Range to summarize:
```
from_ref..to_ref
```
(tags/SHAs/branches). If unknown, ask: "last release tag?" and "target branch/tag?"
Target audience: end users, developers, internal ops, or all.
What to include/exclude: internal refactors, dependency bumps, infra-only changes.

发布版本 + 发布日期（或标注为"unreleased"）。
待汇总的变更区间：
```
from_ref..to_ref
```
（tags/SHAs/分支）。如果信息未知，可询问："上一个发布tag是？"以及"目标分支/tag是？"
目标受众：终端用户、开发者、内部运维人员，或全部受众。
内容包含/排除规则：内部重构、依赖版本升级、仅涉及基础设施的变更是否需要纳入。

Workflow (checklist)

工作流（检查清单）

Determine the release range
- Prefer tags: pick the previous tag and the new tag/HEAD.
- If no tags: use the last release branch point or a date-based window.
- Commands to gather candidates:
  - ```
  git tag --sort=-creatordate | Select-Object -First 20
```
- ```
git log --first-parent --oneline <from_ref>..<to_ref>
```
  - If GitHub CLI is available: list merged PRs for the range and use titles for grouping.
Collect and categorize changes
- Start from merge commits (first-parent) to avoid noise.
- Categorize into: Highlights, Breaking changes, Features, Fixes, Performance, Security, Deprecations, Docs, Dependencies, Infra/ops.
- Flag anything requiring action: config changes, env vars, DB migrations, API contract changes.
Identify breaking changes and upgrade steps
- Look for: renamed/removed endpoints, changed request/response fields, changed config keys, Java/Kotlin/Node version bumps, DB schema changes.
- Add explicit "Upgrade" and "Rollback" notes when impact is non-trivial.
Write release notes using the template
- Use short bullets, active voice, and user-facing wording.
- Prefer "what changed" + "why it matters" over implementation details.
- Include PR/issue references only if they are stable in your repo hosting.
- Use
```
references/release-notes-template.md
```
  to keep structure consistent.
Sanity check for omissions and accuracy
- Diff the range:
```
git diff --stat <from_ref>..<to_ref>
```
- Scan for config/migrations:
```
rg -n \"ENV|config|migration|Flyway|Liquibase\" -S
```
- Ensure breaking changes are called out and have upgrade steps.

确定发布区间
- 优先使用标签：选取上一个发布标签和新标签/HEAD。
- 若无可用标签：使用上一个发布分支的分叉点，或基于日期的时间窗口。
- 收集候选变更的命令：
  - ```
  git tag --sort=-creatordate | Select-Object -First 20
```
- ```
git log --first-parent --oneline <from_ref>..<to_ref>
```
  - 如果安装了GitHub CLI：列出该区间内的已合并PR，使用PR标题进行内容分组。
收集并分类变更
- 从合并提交（first-parent）开始梳理，避免无关冗余信息。
- 变更分类：亮点功能、破坏性变更、新特性、问题修复、性能优化、安全更新、弃用通知、文档更新、依赖变动、基础设施/运维变更。
- 标记所有需要用户采取行动的内容：配置变更、环境变量调整、数据库迁移、API契约变更。
识别破坏性变更和升级步骤
- 重点查找：重命名/移除的接口、变更的请求/响应字段、变更的配置键、Java/Kotlin/Node版本升级、数据库schema变更。
- 当变更影响较大时，添加明确的「升级」和「回滚」说明。
基于模板编写发布说明
- 使用简短的项目符号、主动语态、面向用户的表述。
- 优先说明「变更内容」+「对用户的价值」，而非具体实现细节。
- 仅当PR/issue链接在你的代码托管平台上稳定可访问时，才添加相关引用。
- 使用
```
references/release-notes-template.md
```
  保持文档结构统一。
完整性与准确性校验
- 对比区间文件差异：
```
git diff --stat <from_ref>..<to_ref>
```
- 扫描配置/迁移相关变更：
```
rg -n \"ENV|config|migration|Flyway|Liquibase\" -S
```
- 确保所有破坏性变更都已明确标注，且附带对应的升级步骤。

Deliverable

交付物

Provide:

Release notes Markdown (ready to paste into a GitHub Release / changelog).
A short "Risk/notes" section listing any required migrations, config changes, or rollback concerns.

提供以下内容：

Markdown格式的发布说明（可直接粘贴到GitHub Release / 变更日志中使用）。
简短的「风险/注意事项」章节，列出所有需要执行的迁移、配置变更或回滚相关注意点。