changelog-writing

CHANGELOG 写作（dsh-config-manager）

这份 changelog 是发布说明的唯一来源：打 tag 时 CI 直接抽取当前版本段当 GitHub Release 描述。 读者是想知道「这个版本给了我什么」的用户，不是维护这份代码的人。 所以一条 = 一个用户能看懂的更新或修复，一句话说完。

改了什么文件、哪个测试钉住、根因是什么、接口字段怎么变 —— 这些不进这里：它们的去处是 commit message、PR 与 docs/lessons/。

本 Skill 只规定落位、体例与自检；具体改哪些功能、有没有发布权限由当前任务决定。

何时使用 / 何时跳过

用：

• 用户可见的变化（新功能 / 行为变更 / 修复 / 移除 / 安全）准备写进 CHANGELOG 时。
• 发版前补「当前版本亮点段」时。

跳过：

• 只改注释、重构、内部测试，且用户可感知行为没变（这类不写条目）。
• 纯文档改动（除非它改变了用户的操作方式）。

1. 落位：写进哪一段

• 文件 = 仓库根 CHANGELOG.md，格式遵循 Keep a Changelog。

• 未发布的内容一律写进 ## [Unreleased]，按改动性质分组，顺序固定：

  分组	放什么
  ### 🆕 新增 · Added	新功能、新来源、新通道、新入口
  ### 🔧 变更 · Changed	行为/口径改变、原本静默的变可见、性能与体验变化
  ### 🐛 修复 · Fixed	修 bug、修误报、补护栏
  ### 🗑️ 移除 · Removed	删功能（有内容才写这个标题）
  ### 🔐 安全 · Security	安全修复（有内容才写这个标题）

• 没有内容的分组不写标题；分组之间空一行。

• 已发布的历史版本段保留当时写法，不回改（那 40 多个版本段是发布记录，整批重排只会产生巨大无意义 diff）。用户明确要求时才动。

2. 体例：一句话一条

每条 = 一个 bullet、两行（中文一行 + 英文缩进续行），骨架：

- **<功能名>**：<用户视角的一句话>。（issue #75）
  **<English title>**: <one-line user-facing sentence>.

• 一个功能一条，不是一次提交一条：同一功能的连续迭代与补丁合并进那一条，不写「第二轮」「再次修复」。
• 一批同类小修复合成一条，必要时用括号列要点。
• issue 号可选，放句末（（issue #75）），便于溯源。
• emoji 可选：分组标题必须带（见上表）；条目内可用（🔌 🧩 🐛 🔐 等本仓已有用法）。

一句话里写什么

• 用户能做什么、行为变成了什么：「现在可以…」「不再…」「改成…」。
• 用户能感知的数字可以留（「1347 条会话也能秒开」），不带内部口径与实现过程。

一句话里禁止出现什么（本仓最看重的一条）

禁止	例子	该去哪
文件 / 路径 / 符号名	src/core/rollback-point.ts、withLedgerWriteLock	commit message
测试文件名与用例数	rollback-view.test.ts 新增 3 条	测试文件本身
字段 / 接口 / 码值细节	payload.pathIndex、HTTP 400、409 plan-changed	docs/spec/
根因与实现过程	「旧实现让首个文件因 read>0 短路绕过上限」	docs/lessons/
内部代号	t13 / S4 / F2 / G-30 / t5-F1	不入库
「未验证」声明	NOT VERIFIED、未做浏览器取证	commit message

口径纪律（不变）

• 不得夸大：没做的写没做（「只报不修」「真机未逐家验证」）。
• 不把计划写成已完成：还没合并 / 还没验证的东西不进 changelog。
• 不承诺未发布的版本号：发版前不写「将在 v0.1.x 修复」。
• 结论要能被代码证伪：写下的每一句都要有对应实现；证据（哪个测试、哪个脚本）留在 commit 与测试里，不写进条目。