用途:本技能适用于任何使用 Towncrier 的项目。Towncrier 会在发布时把每次变更的“片段”文件汇总渲染成变更日志,因此每次缺陷修复或新功能都应附带一个片段,内容面向用户,说明改了什么而非如何实现。
核心规则:始终使用 towncrier create 创建片段,不要手写。该命令会依据 Towncrier 配置推导位置与命名,并从仓库任意位置正确放置文件。
使用时机:修复缺陷或新增功能、即将提交或开 PR 时;被要求“添加 changelog 条目”“创建 news fragment”或“运行 towncrier”时;PR 检查清单或 CI 提示缺少 changelog 条目时。不适用:项目未使用 Towncrier;纯内部重构且无用户可见或维护影响;团队明确决定无需条目的变更(多数内部维护仍会写 housekeeping 片段)。
命令示例:uv run towncrier create -c "content of changelog entry" ${ISSUE}.${TYPE}.md。使用 uv run 运行项目锁定的 Towncrier;若项目不用 uv,可去掉前缀或改用其运行器(如 poetry run towncrier ...)。ISSUE 为 issue 编号,无 issue 时用 +(如 +pnpm-workspaces)。
类型:added(新功能)、changed(现有功能变更)、deprecated(即将移除)、removed(已移除)、fixed(缺陷修复)、security(安全漏洞)、housekeeping(内部维护与工具)。可用类型来自项目 Towncrier 配置,以上为常见默认值;某些变更分类因项目而异(尤其依赖版本升级),应遵循项目变更日志指南。
片段位置:位于 Towncrier 配置的目录(常见为仓库根的 changelog/ 或 newsfragments/),towncrier create 会自动放入,不要移动或手动放置。单体仓库中不应放在 backend/changelog/ 等子包目录,除非该嵌套包有自己的 Towncrier 配置(如 Infrahub 的 python_sdk),这些片段应留在原处。
写作要点:从用户视角,关注变化而非实现,使用过去时,一句话,避免技术术语。示例:uv run towncrier create -c "Fixed sidebar collapse issue" 1234.fixed.md。
常见错误:手写片段;放入子包目录;描述实现细节(应改为用户可见结果);时态错误或多句。
参见:Towncrier 文档、Keep a Changelog,以及项目贡献或变更日志指南(Infrahub 为 docs/docs/development/changelog.mdx)。