# 发布说明标准（Release Notes Style Guide）

> 本文件是**强制规范**：所有 GitHub Release 的说明都按此写，历史版本也要逐步对齐。
> 参考体例：[Claude Code changelog](https://code.claude.com/docs/en/changelog)。

## 结构

```markdown
## v<版本> — <YYYY-MM-DD>

**新增**
- …

**优化**
- …

**调整**
- …

**修复**
- …

**移除**
- …
```

- **Release 标题就是纯版本号**（`v1.1.9`），不加「— 插件市场与停止修复」这类副标题。
  参考 Claude Code：`title=v2.1.263` / `title=v2.1.261`，全部只有版本号。
- 版本头**只写版本号 + 日期**，不要把功能清单堆进标题。
- 分组标题固定用这五个：`新增` / `优化` / `调整` / `修复` / `移除`（英文版对应 Added / Improved / Changed / Fixed / Removed）。
- **空的分组不写**；只有一条修复的版本就只写「修复」。
- 每条一行，动词开头，句末不加句号（多条并列时统一）。

## 写作规则

**写用户能感知的变化，不写实现细节。**

| 要写 | 不要写 |
|---|---|
| 「修复点击『停止服务』无反应、服务仍在运行的问题」 | 「旧写法在 stop 分支先置位标志再调用 stopServer()…」 |
| 「设置页新增『插件市场』，一键安装后自动重启服务生效」 | 「执行 dsh plugin --profile web add dshmarket@<版本> -w…」 |
| 「自动回退到上一个正常配置」 | 「health.pickRestoreTarget + skip marker 消费…」 |

**不要出现**：文件名、函数名、行号、变量名、IPC 通道名、根因分析、验证过程（`npm test 60/60`、`selftest 全绿`）、提交号、内部术语（除非是用户可见的功能名，如 `dshmarket`）。

**术语**：用用户界面上的原词（「停止服务」「运行环境」「插件市场」「独立窗口」），不要用代码里的叫法（`stopServer`、`envInstall`、`webWin`）。

**粒度**：一个用户能理解的功能点 = 一条。不要把一个功能拆成三四条，也不要把多个功能塞进一条。

**长度**：每条一行、尽量 ≤ 40 字；一个版本的说明通常 3–10 条。补丁版本只有一条修复是正常的，写一句即可（参考 Claude Code 的「Bug fixes and reliability improvements」）。

## 检查清单（发布前逐条过）

- [ ] Release 标题是纯版本号（`vX.Y.Z`），没有副标题
- [ ] 版本头是 `## vX.Y.Z — YYYY-MM-DD`，没有多余文字
- [ ] 分组只用了 新增/优化/调整/修复/移除，且没有空分组
- [ ] 每条都是动词开头、一行、无句号
- [ ] 没有文件名/函数名/测试结果/提交号
- [ ] 术语与界面文案一致
- [ ] 用户读完能知道「这个版本对我有什么用」

## alpha 与正式版的口径（2026-09-16 起）

- **alpha 不发公告**：alpha 是内部验证版，内容还会变、甚至可能回退 —— 先公告等于对不特定用户承诺了可能改的东西。
  每个 alpha 的更新内容只写进 [release-notes-alpha.md](release-notes-alpha.md)（本地留档、随仓库提交），
  GitHub Release 正文只留一句占位说明。
- **转正式版（latest）时才公布**：把这条 alpha 线的留档条目整理进**正式版**的发布说明（挂到正式版本号下）。
  `tools/release.mjs` 在发正式版且没给 `--notes-file` 时会**自动汇总**同一条 alpha 线的条目；给了文件则以文件为准。
- 因此**写 alpha 条目时就要按正式版的标准写**（五个分组、每条一行、动词开头、不写实现细节），转正式版时不必重写。

## 自动化

- `tools/release.mjs` 会自动生成版本头与日期，并把最终说明打印到终端（发布前先看一眼）；标题固定为 `vX.Y.Z`。
- 说明正文从命令行参数或 `--notes-file` 取；alpha 会把它追加到 `docs/release-notes-alpha.md`，正式版会把它发成公告。
  **不要**用 git 提交列表当发布说明（脚本的兜底分组仅供应急）。