CHANGELOG.md 由外部工具生成，与 Composer 无关，需满足三条件：精确 Git tag 与 version 一致、遵循 Keep a Changelog 规范、工具驱动而非手动维护；推荐 conventional-changelog-cli、git-cliff 或 standard-version。
Composer 本身不生成、不读取、不验证 CHANGELOG.md —— 它只认 composer.json 里的 version 字段和 Git tag。 所谓“用 Composer 生成变更日志”，其实是人借助外部工具，按规范维护一份人类可读的版本记录，再与 tag 同步发布。
CHANGELOG.md 的作用和硬性约束
它不是给 Composer 看的，是给使用者快速判断「这个版本值不值得升」「我遇到的 bug 是否已修复」用的。必须满足三个条件，否则就失去意义：
- 每个发布版本（如
v3.2.0）必须对应 Git 中一个精确的 tag，且 tag 名与composer.json中的version严格一致 - 内容必须遵循 Keep a Changelog 规范：分
Added/Changed/Fixed段落，不写模糊描述（比如别写「优化性能」，要写「HttpClient::send()默认超时从 30s 降为 10s」） - 不能靠手动拼写维护——容易漏、易错位、难对齐，必须用工具驱动生成
推荐的命令行工具（基于 conventional commits）
真正能闭环支撑 CHANGELOG 流程的，是那些能解析 Git 提交信息并自动生成日志的工具。它们不依赖 Composer，但能和 Composer 发布流程无缝衔接：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
-
conventional-changelog-cli：最主流选择，支持多种 preset（angular、eslint、conventionalcommits），执行npx conventional-changelog -p angular -i CHANGELOG.md -s即可追加最新提交生成的条目 -
git-cliff：Rust 编写的高性能替代品，配置灵活（通过 TOML），能精准匹配 tag 范围生成日志，适合 CI 自动触发：git-cliff --unreleased --tag v2.1.0 --output CHANGELOG.md -
standard-version：集 commit 校验 + 版本 bump + CHANGELOG 生成 + Git tag 创建于一体，一条命令完成发布准备：npx standard-version --release-as 2.1.0
为什么不要用 composer show --tree 或 composer depends 生成 CHANGELOG
这些命令展示的是依赖结构，不是行为变更。常见误操作包括：
- 把
composer show --tree monolog/monolog输出当成变更说明，结果里面全是包名和版本号，没有一行功能描述 - 在
composer.json里改了require版本后，以为自动触发了 CHANGELOG 更新，其实什么都没发生 - 用
composer prohibits查兼容性问题，却误把它当成功能更新日志贴进 CHANGELOG
这类命令解决的是依赖解析问题，不是版本叙事问题——混淆二者会导致日志不可信、协作成本陡增。
最容易被忽略的一点：CHANGELOG 不是「补丁清单」，而是「用户影响清单」。哪怕内部重构了十个类，只要对外 API 和行为没变，CHANGELOG 就不该出现；反之，哪怕只改了一行超时配置，只要会影响调用方，就必须明确写出。这个边界，工具不会替你判断，得靠人盯着。
