agentleFS
imchangchangimchangchang/dsh-one/.agents/skills/changelog-conventions/SKILL.md

changelog-conventions

Skill1 starsChanged 55 days agoMITView on GitHub

dsh-one CHANGELOG 的写法约定——面向终端用户,一句话讲清「做了什么、对用户有什么影响」,不写实现细节(函数名/符号/行号/内部术语)。按可判定的分类规则产出,任何 session 按同一份规则会得到一样的条目归属与措辞。当要写/改 CHANGELOG 条目、版本收口、review 发布条目时用。正式版发布收口时按此风格审查全部条目。

2 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 2

    1. michel-kraemer/zsh-patina★ 568same name
    2. lossless-group/lossless-agent-skills★ 4same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository5 other files it gives its agents.

The file

Files
SKILL.md

CHANGELOG 写法约定

CHANGELOG 是给用户看的:用户只看「这个版本对我有什么影响」,不看你代码怎么改的。技术细节放 commit message 和 backlog issue,CHANGELOG 只留结果。

目标:同一份变更清单,任何人按本规则写,产出一样的节归属、一样的措辞。为此每条、每节的归属都用可判定标准定死,少留主观空间。

一条怎么写

模板:

<短关键词>:<一句用户话,讲「对内影响」>
  • 短关键词:开头一个用户能认识的功能词(输入框、会话列表、侧栏、快捷键、标签组、回收站……),方便扫读。
  • 一句用户话:讲结果,不解释实现。「做了什么 + 现在是什么样」,结尾是用户能观察的状态或动作。
  • 一条一行;信息多时一行内最多两句短句,不展开成段、不加括号解释成因。

硬规则(写之前先过一遍)

  1. 每条 = 一句用户话,不解释实现。
  2. 不写:函数名/变量名/键名、文件路径与行号、内部术语(wire 协议、对账、签名、宿主、PTC 等只有维护者懂的词)、无说明的 slug/代号。
  3. 用户无感的技术活(重构、死代码清理、内部优化):不单列,合并为一句「内部优化」,或归 Changed 一句带过;纯内部改动也可以直接不写。
  4. 版本收口:正式版把 [Unreleased] 收口成版本号;-rc.N 预发布不消费 CHANGELOG([Unreleased] 保留)。
  5. 破坏兼容的改动(升级后用户看到的行为变了)必须在条目里一句话点明(用户需要知道)。

分类判定(一条归哪节,按此定死)

按顺序向下问,命中即停,不要多条命中选择:

  1. 是否用户无感?(重构/清理/内部优化/纯兼容适配不改变用户可见行为)→ 归 内部优化;若只是用户习惯不变但代码大幅改动,也归此或省略。
  2. 是否适配上游 dsh 版本变动?(换了 dsh 版本、字段/协议变了才让功能照常)→ 归 上游兼容性。
  3. 之前是坏的、现在修好了?(原来不能用/不对,现在能用/对了)→ 归 Fixed。
  4. 是全新能力或全新入口?(以前完全没有,用户第一次能这么做)→ 归 Added。
  5. 剩下的(已有功能、行为/表现变了但仍正常工作)→ 归 Changed。

各节定义

节判定例
Added全新能力/入口,用户第一次能做新增标签组:可按自定义标签给会话分组
Changed已有东西变了但没坏会话行状态标记移到行尾时间位,互斥显示
Fixed原来坏了/不对,现在好了排队消息切换会话后不再丢失
上游兼容性换了上游 dsh 版本后仍照常dsh 0.1.3 兼容:升级后流式输出照常
内部优化用户无感的重构/清理前端组件抽取共享基座

优先级再强调:内部优化 > 上游兼容性 > Fixed > Added > Changed。一条只归一处,不跨节重复。同一批改动拆成多条时,各条按各自性质归节,不因「同一批」强行并节。

正例 / 反例

反例(技术味重,来自历史条目):

插话快捷键占位符按平台区分文案(steer-shortcut-copy-per-platform):会话运行中的 composer 占位符原来一律显示「⌘Enter 插话」,Windows/Linux 用户键盘上没有 ⌘ 键。现在附着会话的 ChatState 常态下发宿主平台(hostOs),macOS 保持 ⌘Enter,Windows/Linux 显示 Ctrl+Enter(按键处理本就 metaKey||ctrlKey 全平台可触发,纯文案修正);hostOs 未知时回退 ⌘ 版原文案。

正例:

插话快捷键提示按平台显示:Windows/Linux 显示 Ctrl+Enter,不再一律显示 ⌘Enter。

再一组对照作者角度:函数签名、host 版本探测、wire 帧翻译在 CHANGELOG 里都不出现——用户只关心「换到 0.1.3 后聊天流式照常、斜杠命令照常」。

流程挂点

  • 开发中:改动涉及用户可见行为 → 更新 CHANGELOG.md 的 [Unreleased] 段(按本约定),随功能合入。上次收口后 [Unreleased] 会被消费成版本号(文件里只剩历史版本),没有这一节就新起一段放在最上面——release-gate.sh 收口时要它存在。
  • 发版前:收口时逐条复核,把技术味儿重的条目改写成用户话(release-gate 流程里审查 CHANGELOG)。
  • 验收:人工过一遍「每条是否问得出『用户看这句能知道什么』」,答不出就重写。

审校清单(收口/自检时逐条打勾)

  • 每条开头有短关键词。
  • 每条是一句用户话,没有函数名/路径/行号/内部术语/slug。
  • 每条只归一个节;分类按「判定优先级」定死,没有可归属多处。
  • 一条占用一行,不超过两句短句。
  • 用户无感的重构没混进 Added/Fixed,只在内部优化或省略。
  • 上游 dsh 版本适配在「上游兼容性」,不在 Fixed。
  • 破坏兼容的改动(若有)在条目里一句话点明。

边界

  • README / 用户文档(docs/)不受本约定约束(面向安装/排障,允许技术细节);只约束 CHANGELOG.md。
  • 本约定只管 CHANGELOG.md;commit message 与 backlog issue 仍写技术细节。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.