changelog.md 对 composer 完全透明，其生效依赖 git tag、composer.json 的 version 字段与 changelog 中 ## [x.y.z] 标题三者严格一致；任一不匹配则 packagist 不索引，日志失效。
CHANGELOG.md 对 Composer 完全透明，它只看 composer.json 的 version 字段和 Git tag；你写的日志再漂亮，只要没对齐 tag，用户就看不到。
为什么改了 CHANGELOG 却没人看到
常见错误是本地写了 ## [2.1.0]，但 Git 仓库没打 v2.1.0 tag，或者 composer.json 里写的是 "version": "2.1.1"。Packagist 同步时会校验三者一致性：tag 名、composer.json 中的 version、CHANGELOG 里的标题。任一不匹配，该版本就不会被索引，CHANGELOG 段落也就彻底失效。
- 执行
git tag确认当前 tag 列表是否包含目标版本（注意前缀v） - 运行
composer validate检查composer.json是否合法，尤其version字段格式 - 确保 CHANGELOG 中标题为
## [2.1.0] - 2026-05-21，日期必须是实际发布日，不是 commit 日 - 别用
## v2.1.0或### [2.1.0]—— Keep a Changelog 只认## [x.y.z]
怎么写才算真正有用的条目
用户翻 CHANGELOG 不是为了读散文，而是快速判断「我该不该升」「我的报错是不是已修复」。模糊描述如「优化配置加载」或「修复若干问题」等于没写。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 每条以
Added/Changed/Deprecated/Removed开头，不用Update或Fixed - 动词后直接跟可观察行为：
Added Config::getRequired() method that throws exception on missing key (#47) - 涉及 BC break 必须标注旧→新路径：
HttpClient::send() timeout default changed from 30s to 10s - 每条末尾附 PR 或 issue 编号，方便追溯上下文
- 禁止跨版本混写：旧版本的
Fixed条目绝不能塞进新版本段落里
如何验证 CHANGELOG 是否生效
别等用户反馈才发现日志白写了。最直接的验证方式是模拟 Packagist 的视角：
- 删掉本地
vendor/和composer.lock - 执行
composer install --no-dev，确认安装的是目标 tag（如v2.1.0） - 打开
vendor/vendor-name/package-name/CHANGELOG.md，检查对应版本段落是否完整可见 - 如果看不到，回退检查：Git tag 是否推送？
git push --tags容易漏 - 如果看到但格式错乱，大概率是 Markdown 解析失败——用 Keep a Changelog 官方校验器粘贴内容测试
最容易被忽略的一点：CHANGELOG 不是发布流程的终点，而是起点。它必须在 tag 推送前完成，并和 composer.json 版本号同步提交。任何「先发版再补日志」的操作，都会让那部分变更对使用者不可见。
