Composer 不自动生成 CHANGELOG.md，需用 conventional-commits 规范约束提交并借助工具生成初稿；必须校验 Git tag 与 composer.json version 一致，否则 Packagist 同步失败；PR 应明确填写用户可见的变更条目，CHANGELOG 是发布后的静态快照。
Composer 本身不生成、不读取、不验证 CHANGELOG.md，所谓“自动化生成”，其实是用外部工具链把 Git 提交历史、PR 元数据、版本 tag 和 composer.json version 对齐后，输出符合 Keep a Changelog 规范的文本文件——这个过程必须人工校验，否则极易出错。
怎么从 Git 提交提取变更条目
直接解析 git log 不可靠：提交信息格式随意、包含合并记录、混杂 CI 或文档改动。推荐用 conventional-commits 规范约束提交，并配合工具生成初稿：
- 要求团队使用
feat:、fix:、refactor:等前缀，例如fix: HttpClient::send() timeout default from 30s to 10s (#45) - 用
conventional-changelogCLI（或 GitHub Actionconventional-changelog-action）按 tag 自动生成段落 - 注意过滤掉
chore:、docs:、ci:类型提交，它们不属于用户可见变更 - 如果项目未强制 conventional commits，可用
git log v2.1.0..v2.2.0 --oneline | grep -E "(#|PR|Fix|Add)"手动筛，但不可靠
为什么不能跳过 Git tag 和 composer.json version 校验
CHANGELOG 的标题如 ## [2.2.0] - 2026-08-20 必须与实际发布的 Git tag 名称和 composer.json 中的 "version" 字段完全一致。否则 Packagist 同步失败，或用户执行 composer require vendor/package:^2.2 时根本拉不到对应版本。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- CI 发布流程中，必须在打 tag 前先更新
composer.json的version字段，顺序错误会导致锁文件与 tag 不匹配 - 用
git describe --tags --exact-match HEAD检查当前 commit 是否有精确 tag，再比对jq -r '.version' composer.json - GitHub Actions 中可加一步：
if: ${{ steps.tag-check.outputs.match == 'true' && steps.version-check.outputs.match == 'true' }}
如何让 PR 自动关联到 CHANGELOG 条目
CHANGELOG 不是提交日志的复刻，而是面向使用者的功能/修复摘要。PR 描述需明确写出「用户能感知的变化」，而非内部实现细节。
- PR 模板里强制填写
## Changelog Entry区块，示例：Fixed YAML parsing crash on empty arrays (#45) - CI 脚本可提取 PR body 中该区块内容，追加进待生成的 CHANGELOG 片段
- 禁止出现模糊描述，如
Improved performance或Updated dependencies；必须写清影响范围和行为变化 - 若 PR 修改了
require-dev中的phpunit/phpunit，且未改变用户 API，则不应出现在 CHANGELOG 中
最常被忽略的一点：CHANGELOG 是发布后才生效的静态快照，不是实时文档。你在 main 分支提前写好 ## [3.0.0] 段落，但没打 tag、没更新 composer.json、没同步到 Packagist——那它就只是个 Markdown 文件，对 Composer 和用户都毫无意义。
