Python 项目 changelog 自动化生成方法

本文深入解析了 Python 项目中 changelog 自动化生成的两种主流方案——团队协作推荐使用不依赖 commit 格式的 towncrier（通过 changelog.d/ 碎片文件聚合，规避 rebase 和格式卡点问题），而个人项目或已采用 Angular 提交规范的则更适合轻量级的 conventional-commits + cz-cli 组合；文章不仅给出明确选型结论，还直击实操痛点：从 towncrier 常见配置遗漏、emoji 支持、CI 权限陷阱、时区差异，到历史 commit 补救和 GitHub Actions 集成技巧，覆盖从本地开发到自动化发布的全链路关键细节，帮你避开踩坑、真正落地可维护的版本日志管理。

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 十有八九报错，不是缺配置就是路径不对。

实操建议：

• 必须在项目根目录放 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\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}，发布时再手填。

事情说清了就结束

终于介绍完啦！小伙伴们，这篇关于《Python 项目 changelog 自动化生成方法》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布文章相关知识，快来关注吧！