用途:为使用 antsibull-changelog(Ansible 集合)、towncrier 或 scriv(多数其他 Python 包)的 Python 项目创建并校验变更日志片段。三者都是 PR 维度的片段,发布时再汇总进正式变更日志,但文件格式、配置段和目录约定不同。
主要能力与用法:
- 先判断项目使用哪个工具。标记为:changelogs/config.yaml 或 changelogs/fragments/ 对应 antsibull-changelog;pyproject.toml 中的 [tool.towncrier] 对应 towncrier;pyproject.toml 中的 [tool.scriv] 或 setup.cfg、tox.ini 中的 [scriv] 对应 scriv。towncrier 与 scriv 常用名为 changelog.d/ 的目录,需按配置段名而非目录名区分。若都不存在,应询问项目使用哪个工具,不可猜测,片段格式和目录不通用。
- 加载对应工具的参考文件:antsibull-changelog 读 references/antsibull-changelog.md;towncrier 读 references/towncrier.md(片段命名 <issue>.<type>.md);scriv 读 references/scriv.md。
- 编写片段:与目录内已有片段的语气和类型保持一致,不新建类型;每个面向用户的变化一个片段;写成面向最终用户的变更日志条目而非提交信息;写具体效果而非“更稳健”“更完善”等空洞说法;不写“旨在修复”“应能解决”等模糊措辞,真实已知限制应明确说明;去掉连接性填充语与 AI 式表述;无用户影响的改动(内部重构、仅测试、CI 配置)通常不写片段,除非贡献指南另有要求;文件末尾保留换行。
- 提交前校验:运行对应工具的 lint/check 命令,修复错误的分区名、文件名或无效 YAML/RST/Markdown,校验不通过不得提交。
适用场景:为上述三类 Python 项目补充或审查 PR 变更日志片段。
限制:资料未提供各工具的安装命令、具体片段字段、lint 命令、价格与平台等信息,需查阅对应参考文件;不得在未识别工具时臆测格式。