pytest 补丁版发布公告模板解析从 release.patch.rst 看 pytest 的自动化发版体系【免费下载链接】pytestThe pytest framework makes it easy to write small tests, yet scales to support complex functional testing项目地址: https://gitcode.com/GitHub_Trending/py/pytest本文以 pytest 仓库中的补丁版bug-fix发布公告模板 scripts/release.patch.rst 为切入点完整解读其占位符语法与drop-in replacement语义并结合 scripts/release.py、scripts/prepare-release-pr.py、tox.ini 以及 doc/en/announce/ 目录下的真实公告产物还原 pytest 从模板文件到正式发布公告落盘的自动化链路。读完本文你将掌握 pytest 四种发布公告模板的分工逻辑、模板占位符的填充机制、补丁版发布在整套发版流程中的位置并能复刻这一模板 脚本填充 自动落盘的发布公告工程实践。一、模板是什么补丁版发布公告的标准话术scripts/release.patch.rst全文仅 15 行是 pytest 用于**补丁版bug-fix release**发布公告的 reStructuredText 模板。完整内容如下pytest-{version} pytest {version} has just been released to PyPI. This is a bug-fix release, being a drop-in replacement. The full changelog is available at https://docs.pytest.org/en/stable/changelog.html. Thanks to all of the contributors to this release: {contributors} Happy testing, The pytest Development Team模板由三部分构成版本占位符{version}出现在标题行与正文首句实际发布时被具体版本号替换例如pytest 9.1.1 has just been released to PyPI发布定位声明明确标注 This is a bug-fix release, being a drop-in replacement即该版本只包含缺陷修复、不引入破坏性变更用户可无感升级贡献者占位符{contributors}以 bullet 列表形式罗列本次发布的所有作者与共同作者模板中预置了Thanks to all of the contributors to this release:引导语。该模板的使用边界由模板名约定。scripts 目录下共维护四份同构模板分别对应四类发布场景模板文件适用场景版本增量关键话术差异scripts/release.patch.rst补丁版bug-fixx.y.z1drop-in replacement仅指向 changelogscripts/release.minor.rst特性版featurex.y1.0new features, improvements, and bug fixes附pip install -U pytestscripts/release.major.rst主版本x1.0.0额外提示 breaking changes建议仔细阅读 CHANGELOGscripts/release.pre.rst预发布版rc追加rcN后缀声明 not intended for production use要求 issue 标题带[prerelease]其中 pre 模板还额外支持第三个占位符{doc_version}用于在 changelog 链接中指向特定文档版本见 scripts/release.pre.rst 第 22 行而 patch/minor/major 模板均指向en/stable的最新文档。二、占位符如何被填充release.py 的 announce() 机制模板本身只是静态文本真正让它活起来的是 scripts/release.py 中的announce()函数scripts/release.py#L18-L76。该函数负责读取模板、注入真实数据并落盘为正式公告具体分四步第一步通过 Git 历史收集贡献者。先执行git describe --abbrev0 --tags取最近一个标签作为上一版本构造提交区间{last_version}..HEAD随后用两条git log分别提取区间内所有提交的作者--format%aN与Co-authored-bytrailer--format%(trailers:keyCo-authored-by)后者通过正则Co-authored-by: (.?)从 trailer 行中解析出共同作者姓名。第二步清洗贡献者名单。源码中用一个集合推导式对作者与共同作者去重并过滤掉name.endswith([bot])与name pytest bot的自动化账号避免 bot 出现在人类贡献者致谢中。第三步格式化填充模板。将贡献者姓名按字典序排序后逐行拼成* 姓名的 RST bullet 列表再调用template_text.format(version..., contributors..., doc_version...)完成占位符替换。第四步落盘并登记。生成的公告写入 doc/en/announce/release-{version}.rst同时将新公告插入 doc/en/announce/index.rst 的 toctree 列表顶部按release-前缀行定位插入点最后执行git add将公告纳入暂存。main()scripts/release.py#L127-L144以三个位置参数驱动整个流程version、template_name、doc_version另有--skip-check-links开关。这正是文章开头模板在真实发布中的完整调用语境。三、何时用到补丁模板prepare-release-pr.py 的模板决策逻辑补丁模板并不是随意挑选的其选择规则固化在 scripts/prepare-release-pr.py 的prepare_release_pr()中scripts/prepare-release-pr.py#L95-L102if is_major: template_name release.major.rst elif prerelease: template_name release.pre.rst elif is_feature_release: template_name release.minor.rst else: template_name release.patch.rst判定is_feature_release的依据是对仓库 changelog/ 目录的扫描scripts/prepare-release-pr.py#L63-L65只要该目录中存在*.feature.rst或*.breaking.rst文件即判定为特性版否则就是纯 bug-fix 的补丁版落入release.patch.rst分支。这与 changelog 目录中大量.bugfix.rst、.feature.rst、.breaking.rst碎片文件如 changelog/14884.bugfix.rst、changelog/8593.breaking.rst一一对应——正是这些碎片文件的类型决定了公告采用哪种模板。版本号则完全由 Git 标签推算find_next_version()scripts/prepare-release-pr.py#L144-L162扫描所有形如x.y.z的标签取最大值后主版本递增首位、特性版递增次位、补丁版递增末位预发布再追加rcN后缀。也就是说补丁版公告的版本号天然是(major, minor, patch1)。四、从模板到公告补丁版发布的完整流水线补丁模板的消费端是 tox 环境 tox.ini#L213-L222 中定义的[testenv:release][testenv:release] description do a release, required posarg of the version number usedevelop True passenv * deps colorama pre-commit2.9.3 towncrier commands python scripts/release.py {posargs}该环境声明了colorama彩色日志输出、pre-commit格式化、towncrierchangelog 聚合三个依赖然后转调release.py。pre_release()scripts/release.py#L102-L119将补丁模板串入一条完整流水线announce(version, release.patch.rst, doc_version)——按上文机制生成补丁版公告并登记进 indexregen(version)——通过tox -e regen重新生成文档中的示例输出借助SETUPTOOLS_SCM_PRETEND_VERSION_FOR_PYTEST注入版本changelog(version, write_outTrue)——调用towncrier build --yes --version {version}将 changelog 目录中的碎片合并进 CHANGELOG.rst 与 doc/en/changelog.rstdraft 模式则只预览不写盘见 scripts/release.py#L122-L124fix_formatting()——运行pre-commit run --all-files统一格式check_links()——运行tox -e docs-checklinks校验文档链接可用--skip-check-links跳过最后git commit -a -m Prepare release version {version}并提示推送分支、发起 PR。整个流程可被prepare-release-pr环境tox.ini#L224-L230一键触发其入口命令形如tox -e release -- 9.1.1 release.patch.rst release-9.1.1 --skip-check-links补丁版最终产出的公告实物可在 doc/en/announce/release-9.1.1.rst 中看到其结构完全符合模板预期——标题为pytest-9.1.1正文声明 This is a bug-fix release, being a drop-in replacement贡献者区列出人类维护者姓名而 doc/en/announce/index.rst 顶部的 toctree 也按release-9.1.1在前的顺序登记了历次公告。发布完成后scripts/generate-gh-release-notes.py 还会从doc/en/changelog.rst中按版本标题正则pytest (\d\.\d\.\d\w*) \(\d{4}-\d{2}-\d{2}\)抽取对应条目经 pandoc 从 RST 转为 GFM 格式作为 GitHub Release 的正文——公告模板、changelog、发布说明三者由此构成完整闭环。五、模板化设计的工程价值回顾 scripts/release.patch.rst 这一不足 20 行的文件可以提炼出 pytest 发版公告工程化的三个要点话术与逻辑分离发布定位bug-fix / feature / major / prerelease被固化为四个模板语义不会被临场改写模板选择逻辑集中在 scripts/prepare-release-pr.py 一处避免人为误判数据零手写版本号取自 Git 标签推算贡献者取自git log自动提取与 bot 过滤公告正文完全由脚本填充生成杜绝遗漏或拼写错误流程可编排公告生成只是[testenv:release]流水线的一环与 regen、towncrier、pre-commit、链接检查串联保证每次发布的公告、changelog、文档输出三者始终一致。对于任何需要定期向用户发布版本的 Python 项目这套类型化模板 版本/贡献者占位符 脚本自动落盘的模式都可以低成本复刻是值得借鉴的发布工程样板。【免费下载链接】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），仅供参考