团队协作选 towncrier，个人项目或已用 angular 风格规范的选 conventional-commits + cz-cli；towncrier 不依赖 commit 格式，通过 changelog.d/ 碎片文件聚合，避免 rebase 和格式卡点问题。
changelog 生成工具选哪个：towncrier 还是 conventional-commits + cz-cli
直接说结论：团队协作选 towncrier，个人项目或已用 Angular 风格提交规范的，用 conventional-commits + cz-cli 更轻量。
towncrier 的核心优势是「提交时不管格式，发布时才聚合」——它不依赖 commit message 结构，而是靠 PR 合并前手动/自动往 changelog.d/ 下丢碎片文件。这避免了开发者被 feat(api): add timeout 这类格式卡住，也绕开了 rebase 时 commit message 被改乱导致解析失败的问题。
容易踩的坑：
-
towncrier默认不支持 emoji（比如✨ feat），得配template或改pyproject.toml里的title_format - 如果用 GitHub Actions 自动发布，
towncrier生成 changelog 后必须git add CHANGELOG.md && git commit，否则下次跑会重复追加 -
conventional-commits工具链对 commit message 零容忍：少个空行、多一个空格，standard-version就静默跳过该 commit
towncrier 配置里最常漏掉的三件事
装完 towncrier，光跑 towncrier build 十有八九报错，不是缺配置就是路径不对。
立即学习“Python免费学习笔记（深入）”；
实操建议：
- 必须在项目根目录放
pyproject.toml，且含[tool.towncrier]段；只放towncrier.toml会被忽略 -
directory参数默认是changelog.d/，但这个目录要手动建好，towncrier不会自动创建 - 每个碎片文件名必须带数字前缀和类型后缀，比如
123.feature或456.bugfix；用123.feature.txt会被跳过
示例片段：
[tool.towncrier]
directory = "changelog.d/"
filename = "CHANGELOG.md"
title_format = "{version} ({project_date})"
template = "changelog.rst"
commit message 不规范时，怎么补救 changelog
历史 commit 没按规范写，又不想重写 history？别硬套 conventional-changelog。
更可行的做法：
- 用
git log --oneline v1.2.0..HEAD拿出本轮差异 commit 列表，人工扫一遍，把关键改动对应到changelog.d/下新文件（比如789.feature） - 在
towncrier配置里设start_string = "\n<!-- towncrier release notes start -->\n"，这样生成时只替换标记之间的内容，旧 changelog 其他部分不动 - 如果用 GitHub Release，直接把
towncrier build --version 1.3.0输出粘过去，不走文件写入，彻底避开 Git 冲突
GitHub Actions 里跑 towncrier 的权限和路径陷阱
CI 里 towncrier build 报 FileNotFoundError: changelog.d/ 或权限拒绝，基本是工作流没切对分支或没拉子模块。
关键检查点：
- 确保 Action 使用
actions/checkout@v4并开启fetch-depth: 0，否则towncrier找不到 tag - 如果
changelog.d/是 git submodule，得额外加一步git submodule update --init - 用
towncrier build --yes --version ${{ inputs.version }}时，$inputs.version必须是字符串，传1.3.0数字会触发TypeError
真正麻烦的是时间戳：本地 towncrier 用系统时区，CI 默认 UTC，导致生成的 (2024-05-22) 和本地不一致。解决方法是在 workflow 里加 env: TZ: Asia/Shanghai，或者干脆删掉模板里的 {project_date}，发布时再手填。
事情说清了就结束
