pytest changelog 贡献指南读懂 changelog/ 目录与 towncrier newsfragment 规范【免费下载链接】pytestThe pytest framework makes it easy to write small tests, yet scales to support complex functional testing项目地址: https://gitcode.com/GitHub_Trending/py/pytest导读本文围绕当前仓库中 changelog/README.rst 展开系统讲解 pytest 项目如何借助 towncrier 管理发布日志changelog/目录下的 newsfragment 文件如何命名、如何分类、如何撰写以及它们如何被自动聚合进正式版本发布说明doc/en/changelog.rst。读完本文你将掌握为 pytest或其他采用 towncrier 的项目提交一条规范 changelog 的完整流程并能独立判断某个改动该用哪种分类、如何获得本地预览。一、为什么需要 newsfragmentchangelog/目录的设计初衷pytest 是一个历史悠久、迭代频繁的开源项目几乎每个 PR 都会对用户可见行为产生影响。如果所有改动都由维护者手工维护一份大而全的CHANGELOG极易产生冲突、遗漏与归并困难。pytest 的解决方案是每条改动一个短文件newsfragment每个即将进入下一个版本的改动在 changelog/ 目录下对应一个极短的 ReST 格式文本文件发布时由towncrier工具把这些短文件自动聚合、排序、分类渲染进正式发布说明从仓库根目录 doc/en/changelog.rst 开头的注释可以看到硬性约束You should NOT be adding new change log entries to this file, this file is managed by towncrier.——该文件由工具生成贡献者只允许修改其历史部分以修正笔误新增条目一律走changelog/目录注释中还特别指出pytest 里其他项目常见的news/目录在这里被命名为changelog/。仓库根目录的 CHANGELOG.rst 与 doc/en/changelog.rst 一样都只是 towncrier 生成结果的呈现载体而非手工编辑对象。二、newsfragment 的命名规范ISSUE.TYPE.rst每个 newsfragment 文件必须遵循固定命名格式ISSUE.TYPE.rst其中ISSUE是 issue或 PR编号例如14743TYPE是下面第三节介绍的分类标识扩展名固定为.rst内容为 ReST 格式文本。典型实例如当前仓库中真实存在的文件changelog/14743.feature.rstFull diff:now contains a legend explaining the-symbols in diff output.changelog/14724.improvement.rst--no-summary行为改进见下文示例。changelog/14635.bugfix.rst修复多条测试路径下 fixture 解析失败的问题。编号怎么选issue 还是 PRREADME 给出了明确的取舍原则如果你的 PR 修复了某个已存在的 issue优先使用该 issue 的编号如果改动没有对应 issue可以等 PR 提交拿到 PR 编号后用 PR 编号来命名如2574.bugfix.rst见 CONTRIBUTING.rst 中的写法拿不准分类或编号时可以在 PR 讨论中直接提问不必纠结。三、十种分类类型TYPE详解TYPE是 newsfragment 分类的核心。完整合法的类型集合定义在仓库根目录 pyproject.toml 的[tool.towncrier.type]配置段中共十种类型含义README 说明适用场景feature面向用户的新功能新命令行选项、新行为、新公共 APIimprovement对既有功能的改进通常无需用户干预即可生效例如--junit-xml新增字段、终端配色优化bugfix修复缺陷修正与预期不符的行为doc文档改进重写某个章节、补充缺失文档deprecation功能弃用声明预告未来移除的 API 或行为变更breaking可能破坏既有测试套件的变更移除功能、行为变化vendor随 pytest 打包的第三方库变更依赖捆绑更新packaging面向下游发行版的提示测试调用方式变化、运行时假设、不明显副作用等工具链说明contrib影响贡献者体验的事项运行测试、构建文档、搭建开发环境misc难以归入上述任何类别无法分类的内部改动配置中每种类型还带有name在发布说明中展示的章节标题例如 feature 对应 New features、breaking 对应 Removals and backward incompatible breaking changes与showcontent是否展示条目正文两个属性这些属性直接决定渲染效果。四、撰写内容规范写给用户而非开发者README 特别强调发布说明的读者是 pytest 用户而不是维护者。因此面向用户视角描述改动给用户带来的影响而非只有开发者才关心的内部实现细节使用完整的过去时或现在时句子并正确使用标点README 给出的两个示范Improved verbose diff output with sequences.Terminal summary statistics now use multiple colors.保持精炼towncrier 虽然支持多段落及代码块、列表等格式但对于除feature以外的条目通常建议保持单一段落以免冗长。来自当前仓库的正面示例——changelog/14724.improvement.rst--no-summary now only applies directly to pytests own summary. The flag no longer skips the pytest_terminal_summary hook, so third-party plugins (for example coverage) can still write their terminal summaries.这则条目先一句话概括行为变化再用第二句解释对插件生态的影响完全是用户可感知的表述。五、towncrier 如何把这些文件变成正式发布说明5.1 配置与模板仓库根目录 pyproject.toml 中的[tool.towncrier]段定义了聚合规则package pytest、package_dir src关联包信息filename doc/en/changelog.rst生成结果写入的正式发布说明文件directory changelog/newsfragment 所在目录title_format pytest {version} ({project_date})每个版本标题的格式template changelog/_template.rst渲染所用 Jinja2 模板即 changelog/_template.rst。从 changelog/_template.rst 的模板代码可以看到关键渲染逻辑按章节版本段与分类遍历sections用配置中的name作为章节小标题当某分类的showcontent为真时逐条渲染条目正文并把每个条目关联的 issue/PR 编号转换为指向 issue 跟踪页的链接某分类没有任何条目时则输出 No significant changes.。5.2 生成结果示例doc/en/changelog.rst 中已渲染的真实发布说明展示了最终形态例如pytest 9.1.1 (2026-06-19)下的 Bug fixes 章节以- #14220: Fixed a logic bug...的列表形式列出每条修复并带编号链接。六、本地预览tox -e docs如果你希望在自己提交前看到 newsfragment 在正式发布说明中的最终效果README 提供了验证途径tox -e docs该命令会构建文档包含草稿 changelog 的页面位于doc/en/_build/html/changelog.html可以直观检查自己的条目分类、措辞与渲染结果是否正确。七、完整提交流程从改动到 changelog结合 CONTRIBUTING.rst 中的开发者流程一次规范的 changelog 提交包含以下步骤完成代码改动并自测例如pytest testing/test_config.py运行相关测试在changelog/目录创建 newsfragment 文件命名为issueid.type.rsttype从上述十种类型中选取如果改动不影响 pytest 的文档化行为可以跳过该步骤CONTRIBUTING 明确允许按字母序把贡献者信息补充到根目录 AUTHORS 文件提交 PR用tox -e docs预览 changelog 效果。结语changelog/目录加 towncrier 的组合是 pytest 在大量贡献者协作场景下保持发布日志高质量、低冲突的关键机制命名规则决定了归类写作规范决定了可读性工具链负责最终聚合。下次为 pytest 提交改动时只需记住changelog/编号.类型.rst这一条公式再按照面向用户、完整句子、单一段落的原则写出描述即可轻松产出符合项目规范的发布说明条目。【免费下载链接】pytestThe pytest framework makes it easy to write small tests, yet scales to support complex functional testing项目地址: https://gitcode.com/GitHub_Trending/py/pytest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
pytest changelog 贡献指南：读懂 changelog/ 目录与 towncrier newsfragment 规范
pytest changelog 贡献指南读懂 changelog/ 目录与 towncrier newsfragment 规范【免费下载链接】pytestThe pytest framework makes it easy to write small tests, yet scales to support complex functional testing项目地址: https://gitcode.com/GitHub_Trending/py/pytest导读本文围绕当前仓库中 changelog/README.rst 展开系统讲解 pytest 项目如何借助 towncrier 管理发布日志changelog/目录下的 newsfragment 文件如何命名、如何分类、如何撰写以及它们如何被自动聚合进正式版本发布说明doc/en/changelog.rst。读完本文你将掌握为 pytest或其他采用 towncrier 的项目提交一条规范 changelog 的完整流程并能独立判断某个改动该用哪种分类、如何获得本地预览。一、为什么需要 newsfragmentchangelog/目录的设计初衷pytest 是一个历史悠久、迭代频繁的开源项目几乎每个 PR 都会对用户可见行为产生影响。如果所有改动都由维护者手工维护一份大而全的CHANGELOG极易产生冲突、遗漏与归并困难。pytest 的解决方案是每条改动一个短文件newsfragment每个即将进入下一个版本的改动在 changelog/ 目录下对应一个极短的 ReST 格式文本文件发布时由towncrier工具把这些短文件自动聚合、排序、分类渲染进正式发布说明从仓库根目录 doc/en/changelog.rst 开头的注释可以看到硬性约束You should NOT be adding new change log entries to this file, this file is managed by towncrier.——该文件由工具生成贡献者只允许修改其历史部分以修正笔误新增条目一律走changelog/目录注释中还特别指出pytest 里其他项目常见的news/目录在这里被命名为changelog/。仓库根目录的 CHANGELOG.rst 与 doc/en/changelog.rst 一样都只是 towncrier 生成结果的呈现载体而非手工编辑对象。二、newsfragment 的命名规范ISSUE.TYPE.rst每个 newsfragment 文件必须遵循固定命名格式ISSUE.TYPE.rst其中ISSUE是 issue或 PR编号例如14743TYPE是下面第三节介绍的分类标识扩展名固定为.rst内容为 ReST 格式文本。典型实例如当前仓库中真实存在的文件changelog/14743.feature.rstFull diff:now contains a legend explaining the-symbols in diff output.changelog/14724.improvement.rst--no-summary行为改进见下文示例。changelog/14635.bugfix.rst修复多条测试路径下 fixture 解析失败的问题。编号怎么选issue 还是 PRREADME 给出了明确的取舍原则如果你的 PR 修复了某个已存在的 issue优先使用该 issue 的编号如果改动没有对应 issue可以等 PR 提交拿到 PR 编号后用 PR 编号来命名如2574.bugfix.rst见 CONTRIBUTING.rst 中的写法拿不准分类或编号时可以在 PR 讨论中直接提问不必纠结。三、十种分类类型TYPE详解TYPE是 newsfragment 分类的核心。完整合法的类型集合定义在仓库根目录 pyproject.toml 的[tool.towncrier.type]配置段中共十种类型含义README 说明适用场景feature面向用户的新功能新命令行选项、新行为、新公共 APIimprovement对既有功能的改进通常无需用户干预即可生效例如--junit-xml新增字段、终端配色优化bugfix修复缺陷修正与预期不符的行为doc文档改进重写某个章节、补充缺失文档deprecation功能弃用声明预告未来移除的 API 或行为变更breaking可能破坏既有测试套件的变更移除功能、行为变化vendor随 pytest 打包的第三方库变更依赖捆绑更新packaging面向下游发行版的提示测试调用方式变化、运行时假设、不明显副作用等工具链说明contrib影响贡献者体验的事项运行测试、构建文档、搭建开发环境misc难以归入上述任何类别无法分类的内部改动配置中每种类型还带有name在发布说明中展示的章节标题例如 feature 对应 New features、breaking 对应 Removals and backward incompatible breaking changes与showcontent是否展示条目正文两个属性这些属性直接决定渲染效果。四、撰写内容规范写给用户而非开发者README 特别强调发布说明的读者是 pytest 用户而不是维护者。因此面向用户视角描述改动给用户带来的影响而非只有开发者才关心的内部实现细节使用完整的过去时或现在时句子并正确使用标点README 给出的两个示范Improved verbose diff output with sequences.Terminal summary statistics now use multiple colors.保持精炼towncrier 虽然支持多段落及代码块、列表等格式但对于除feature以外的条目通常建议保持单一段落以免冗长。来自当前仓库的正面示例——changelog/14724.improvement.rst--no-summary now only applies directly to pytests own summary. The flag no longer skips the pytest_terminal_summary hook, so third-party plugins (for example coverage) can still write their terminal summaries.这则条目先一句话概括行为变化再用第二句解释对插件生态的影响完全是用户可感知的表述。五、towncrier 如何把这些文件变成正式发布说明5.1 配置与模板仓库根目录 pyproject.toml 中的[tool.towncrier]段定义了聚合规则package pytest、package_dir src关联包信息filename doc/en/changelog.rst生成结果写入的正式发布说明文件directory changelog/newsfragment 所在目录title_format pytest {version} ({project_date})每个版本标题的格式template changelog/_template.rst渲染所用 Jinja2 模板即 changelog/_template.rst。从 changelog/_template.rst 的模板代码可以看到关键渲染逻辑按章节版本段与分类遍历sections用配置中的name作为章节小标题当某分类的showcontent为真时逐条渲染条目正文并把每个条目关联的 issue/PR 编号转换为指向 issue 跟踪页的链接某分类没有任何条目时则输出 No significant changes.。5.2 生成结果示例doc/en/changelog.rst 中已渲染的真实发布说明展示了最终形态例如pytest 9.1.1 (2026-06-19)下的 Bug fixes 章节以- #14220: Fixed a logic bug...的列表形式列出每条修复并带编号链接。六、本地预览tox -e docs如果你希望在自己提交前看到 newsfragment 在正式发布说明中的最终效果README 提供了验证途径tox -e docs该命令会构建文档包含草稿 changelog 的页面位于doc/en/_build/html/changelog.html可以直观检查自己的条目分类、措辞与渲染结果是否正确。七、完整提交流程从改动到 changelog结合 CONTRIBUTING.rst 中的开发者流程一次规范的 changelog 提交包含以下步骤完成代码改动并自测例如pytest testing/test_config.py运行相关测试在changelog/目录创建 newsfragment 文件命名为issueid.type.rsttype从上述十种类型中选取如果改动不影响 pytest 的文档化行为可以跳过该步骤CONTRIBUTING 明确允许按字母序把贡献者信息补充到根目录 AUTHORS 文件提交 PR用tox -e docs预览 changelog 效果。结语changelog/目录加 towncrier 的组合是 pytest 在大量贡献者协作场景下保持发布日志高质量、低冲突的关键机制命名规则决定了归类写作规范决定了可读性工具链负责最终聚合。下次为 pytest 提交改动时只需记住changelog/编号.类型.rst这一条公式再按照面向用户、完整句子、单一段落的原则写出描述即可轻松产出符合项目规范的发布说明条目。【免费下载链接】pytestThe pytest framework makes it easy to write small tests, yet scales to support complex functional testing项目地址: https://gitcode.com/GitHub_Trending/py/pytest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
