Python changelog 的自动化生成

团队协作选 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}，发布时再手填。

事情说清了就结束