changelog.md 应是用户升级指南而非开发日记，需明确回答“该不该升、升了会不会崩、要改哪几行”，按语义分组（added/changed/deprecated/removed/fixed）、动词前置，并确保版本号与tag、packagist同步一致。
为什么你的 CHANGELOG.md 总是没人看
因为多数人把它写成「开发日记」而不是「用户升级指南」。真正的变更日志要回答使用者三个问题：我该不该升级？升级会不会崩？需要改哪几行代码？composer update 之后，用户只扫一眼 Changed 和 Breaking 就决定是否继续——不是看你加了多少行测试。
用 Keep a Changelog 格式但别照抄模板
官方推荐的 Keep a Changelog 是底线，不是上限。关键在「按语义分组」和「动词前置」：
-
Added：新公开 API（如SupportsJsonResponse::toJson()）、新配置项（config/serializer.php中新增'default_encoder'） -
Changed：行为变更但不破坏接口（如Validator::validate()默认启用严格模式） -
Deprecated：标记将在下个主版本移除的函数（LegacyHelper::getRawData()），必须附带替代方案 -
Removed：仅出现在2.0.0这类主版本中，且需在前一版1.x的Deprecated里预告过 -
Fixed：只写影响用户逻辑的修复（如「修复DateTimeFilter在夏令时跨小时解析错误」），不写「修复 CI 超时」
版本号不是 Git tag，而是语义承诺
Composer 包的 version 字段（或 composer.json 中的 "version"）必须与实际发布分支/Tag 一致，否则 composer require vendor/package:~1.2 会拉错包。更常见问题是：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 本地
git tag v1.2.3但没 push：composer install找不到该版本 - Tag 指向了未
git add的修改：发布后用户发现CHANGELOG.md里写的修复根本没进包 - 误用
dev-main当稳定版：CI 构建时用了require-dev里的工具链，导致生产环境composer install --no-dev失败
建议发布前跑一遍：git archive --format=tar v1.2.3 | tar -t | grep -E "(src|CHANGELOG|composer.json)"，确认打包内容和预期一致。
自动更新 CHANGELOG 的工具链要验证两件事
用 conventional-changelog 或 git-cliff 省事，但默认配置往往漏掉 Composer 特有场景：
- PHP 依赖变更不算「功能变更」，但
composer.json中"php": "^8.1"升级到"^8.2"是明确的Breaking，需人工补入 -
autoload规则变动（如从"psr-4": {"App\": "src/"}改为"psr-4": {"App\": "src/App/"}）会导致类加载失败，必须进Breaking - GitHub Actions 自动生成的 Tag 名若含
v前缀（如v2.0.0），而composer.json写的是2.0.0，Packagist 同步会失败——检查packagist.org/packages/vendor/package页面右上角的「Latest release」是否匹配
最常被跳过的动作：每次发版后，立刻用 composer show vendor/package 验证 Packagist 是否已同步、版本号是否可解析、source 链接是否指向正确 commit。这个动作比写十行日志都管用。
