---
name: release-notes
description: 根据已合并的改动、PR 或工单列表，写面向客户的版本更新说明（release notes），分为“新增”“改进”“修复”三组，每条先写用户能得到什么，不出现内部术语和工单编号。同时为团队写一份内部变更日志（changelog）。适用于有人贴来已合并的 PR、Jira 或 Linear 导出、迭代清单，要求写版本说明、更新日志、“新功能介绍”或产品更新时。
---

# 版本更新说明

客户看更新说明只想知道一件事：现在我能做哪些以前做不了的事？每一条都先用他们的话回答这个问题。他们看不到的改动不写，也绝不让他们去猜一个工单标题是什么意思。

## 适用场景

- 发版之后，手上有已合并的 PR、工单或提交信息列表。
- 写“新功能”页面、产品内的更新日志，或每月的产品更新邮件。
- 团队还需要一份带工单编号的内部变更日志，给客服和销售用。
- 不适用于单个重磅功能的发布公告：请用 launch-announcement。

## 需要准备

- 改动列表：PR 标题、工单标题和描述，或提交信息。
- 版本名称或日期。没有的话先问一次，仍没有就写“[发布日期]”。
- 客户是谁，以便选用他们的说法。不清楚的话，按不懂技术的用户来写。
- 可选：新功能对应的帮助文档链接。

## 步骤

1. **去掉客户看不到的改动。** 重构、依赖升级、测试改动、CI、内部工具和日志，只写进内部版本。没有可见效果的改动，不算更新说明。
2. **分到“新增”“改进”“修复”。** 新增 = 用户以前做不了的事。改进 = 以前能做，现在更快、更清楚或范围更广。修复 = 以前坏了、现在好了。工单看不明白的，不要猜，放进内部列表并标注“[待确认：对用户来说改了什么？]”。
3. **每条先写好处。** 先写用户现在能做什么，再写怎么做。写“在‘发票’页面把发票导出为 CSV”，不写“新增 CSV 导出接口”。用产品界面和按钮上的名称，不用代码里的名称。
4. **写修复时，让用户认得出那个问题。** 描述他们看到的现象：“亚洲时区用户的日期不再错开一天。”不要甩锅，也不要过度道歉。从没影响到客户的问题，修复不用写。
5. **按影响排序。** 每组里使用最多或呼声最高的改动放在最前面。对用户来说是同一个改动的多个工单，合并成一条。
6. **压缩篇幅。** 每个改动一条，50 个字以内（这个技能的默认值；通常的建议是一两句话）。只有当某个改动是这次发版的重头戏时，才加一句开头介绍。新功能需要设置时，附上帮助文档链接。
7. **写内部版本。** 采用 Keep a Changelog 的分类：Added（新增）、Changed（变更）、Deprecated（弃用）、Removed（移除）、Fixed（修复）、Security（安全），最新版本在最上面并写明日期。加上工单编号、一个放不可见工作的“内部”分组，以及客服需要知道的事（行为变化、已知问题、迁移步骤）。

## 输出格式

```markdown
## [版本名称或日期]

[可选：用 1 句话介绍最大的改动。]

### 新增
- [用户现在能做什么，在哪里做。][需要设置时附链接]

### 改进
- [哪里变好了，用用户的说法。]

### 修复
- [用户遇到过的现象，现在已修复。]

---

## 内部变更日志 — [版本名称或日期]

### 新增（Added）
- [平实的描述]（[工单编号]，[负责人]）

### 变更（Changed）
- [平实的描述]（[工单编号]）

### 弃用 / 移除（Deprecated / Removed）
- [平实的描述，没有就删掉这一节]（[工单编号]）

### 修复（Fixed）
- [平实的描述]（[工单编号]）

### 安全（Security）
- [平实的描述，没有就删掉这一节]（[工单编号]）

### 内部
- [重构、依赖更新、工具]（[工单编号]）

### 客服需要知道
- [行为变化、已知问题，或“无”]
```

## 示例

**输入：**

> LIN-412 发票列表新增 CSV 导出
> LIN-418 修复到期日选择器的时区偏移 bug（UTC+8 及以东）
> LIN-420 stripe-node 升级到 14.2
> LIN-421 发票列表分页由每页 20 条改为 50 条
> LIN-425 重构 PDF 渲染器
> LIN-426 催款提醒邮件：标题中加入客户的公司名称

**输出：**

```markdown
## 3月12日版本

### 新增
- 在“发票”页面把发票导出为 CSV 文件，可直接放进表格或交给会计。

### 改进
- “发票”页面现在每页显示 50 张发票，少翻几页。
- 催款提醒邮件的标题现在带上客户的公司名称，在收件箱里更醒目。

### 修复
- 亚洲和澳大利亚时区的用户，到期日不再提前一天。

---

## 内部变更日志 — 3月12日

### 新增（Added）
- 发票列表支持 CSV 导出（LIN-412）

### 变更（Changed）
- 发票列表每页条数由 20 改为 50（LIN-421）
- 催款提醒邮件标题加入客户公司名称（LIN-426）

### 修复（Fixed）
- 到期日选择器在 UTC+8 及以东时区的偏移问题（LIN-418）

### 内部
- stripe-node 14.2（LIN-420）
- 重构 PDF 渲染器（LIN-425）

### 客服需要知道
- 按邮件标题过滤催款提醒的客户，可能需要更新过滤规则（LIN-426）。
```

## 发送前检查

- [ ] 面向客户的部分没有工单编号、代码名称，也没有“接口”“重构”“升级依赖”这类词。
- [ ] 每一条都以用户能做什么或会注意到什么开头。
- [ ] 每个改动只出现在一个分组里。
- [ ] 描述没有超出工单内容；看不明白的，在内部列表里标注了“[待确认：……]”。
- [ ] 每一条都在 50 个字以内。

## 常见错误

- 照抄工单标题稍作修改。“修复时区偏移 bug”对客户毫无意义；要描述现象。
- 为了让版本显得内容多，把不可见的工作也列上。这会淹没大家真正关心的改动。
- 在更新说明里预告接下来要做什么。只写已经上线的内容。