尧图网站建设 
pytest 主版本发布公告模板全解从 release.major.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 仓库中的主版本发布公告模板 scripts/release.major.rst 为核心完整拆解该模板的每一处结构与占位符并结合仓库内的发布脚本scripts/release.py、scripts/prepare-release-pr.py与 tox 发布环境tox.ini还原一条从模板填充到发布 PR再到PyPI 部署的完整流水线。读完本文你将理解 pytest 主版本公告major release announcement是如何被自动生成的、它与 minor / patch / prerelease 公告模板有何区别以及维护者手动触发一次主版本发布所需的全部步骤与命令。一、模板定位主版本发布公告的唯一骨架在 pytest 仓库中scripts/目录存放着发布相关的全部脚本与模板。其中release.major.rst是主版本major发布公告专用的 reStructuredTextRST模板全文仅 24 行却是整个发布流程中文档侧的骨架它本身不包含任何版本号或贡献者姓名而是以{version}、{contributors}两个占位符等待发布脚本注入真实数据最终生成doc/en/announce/release-{version}.rst发布公告文件。与该模板并列的还有三个同族模板共同构成 pytest 四类发布公告的模板体系模板文件适用发布类型核心措辞scripts/release.major.rst主版本如 8.0.0、9.0.0proud to announce提示包含新特性、改进、bug 修复与破坏性变更scripts/release.minor.rst次版本如 9.1.0与 major 近似强调新特性与改进scripts/release.patch.rst补丁版本如 9.1.1bug-fix release, being a drop-in replacement即插即用的修复版scripts/release.pre.rst预发布版本如 9.0.0rc1明确标注not intended for production use额外包含{doc_version}占位符四个模板中major 与 minor 的内容结构几乎一致但 major 版在 CHANGELOG 指引语句上更加郑重——因为主版本通常携带破坏性变更breaking changes需要用户仔细阅读变更日志。二、逐段解析 release.major.rst 模板结构原模板全文如下保持原貌未做删改pytest-{version} The pytest team is proud to announce the {version} release! This release contains new features, improvements, bug fixes, and breaking changes, so users are encouraged to take a look at the CHANGELOG carefully: https://docs.pytest.org/en/stable/changelog.html For complete documentation, please visit: https://docs.pytest.org/en/stable/ As usual, you can upgrade from PyPI via: pip install -U pytest Thanks to all of the contributors to this release: {contributors} Happy testing, The pytest Development Team逐块解读如下一级标题pytest-{version}发布公告文档的 H1 标题{version}被替换为完整版本号例如生成pytest-9.1.1。RST 标题下方的是 underline 标记必须与标题等长或更长Sphinx 才能正确解析标题层级。发布宣告The pytest team is proud to announce the {version} release!——标准的主版本宣告句表明这是团队正式发布。CHANGELOG 引导主版本公告特意写明该版本contains new features, improvements, bug fixes, and breaking changes并引导用户仔细阅读官方文档站点的 changelog 页面。这一句是 major 模板区别于 patch 模板bug-fix release, being a drop-in replacement的关键它暗示用户升级前需评估破坏性变更。文档入口给出官方文档总入口便于用户查阅完整文档。升级命令pip install -U pytest是用户从 PyPI 升级的标准命令。值得注意的是预发布模板 scripts/release.pre.rst 中这一命令变为pip install pytest{version}——因为预发布版本必须精确指定版本号不能使用-U通配升级否则会拉到正式版。贡献者致谢区{contributors}该占位符由发布脚本自动填充为按字母排序的* 姓名列表见下文 announce 函数。真实产物示例可参考 doc/en/announce/release-9.1.1.rst其中渲染出的贡献者列表为* Bruno Oliveira、* Ran Benita。落款Happy testing, The pytest Development Team是所有 pytest 发布公告的统一签名。三、模板如何被填充announce() 的源码级实现模板自身只是骨架真正驱动它的是 scripts/release.py 中的announce()函数scripts/release.py。该函数依次完成计算提交区间调用git describe --abbrev0 --tags取得上一个发布 tag构造{last_version}..HEAD作为提交区间用于统计本次发布以来的全部作者。统计贡献者用git log {rev_range} --format%aN收集所有提交作者Author再用git log ... --format%(trailers:keyCo-authored-by)收集协作者Co-author两者合并去重后过滤掉以[bot]结尾或名为pytest bot的自动化账号最终得到真实人类贡献者集合。模板渲染读取Path(__file__).parent.joinpath(template_name)即脚本同目录下的模板文件将贡献者集合按字母序拼接为* name列表行然后调用template_text.format(version..., contributors..., doc_version...)完成占位符注入。这解释了模板中{version}与{contributors}的来源它们与format的关键字参数一一对应。写出发布公告渲染结果写入doc/en/announce/release-{version}.rstscripts/release.py。更新公告索引读取 doc/en/announce/index.rst 的 toctree将新生成的release-{version}条目插入到以release-前缀开头的条目列表最前若已存在则跳过scripts/release.py。仓库中的 doc/en/announce/index.rst 正是这样一份按版本倒序排列的历史公告目录最新版本release-9.1.1位于列表顶部。暂存文件git add生成的公告文件为后续自动提交做准备。四、四种模板的选择逻辑prepare-release-pr.py 如何决策模板不是人工挑选的而是由 scripts/prepare-release-pr.py 依据版本类型自动决定的。该脚本是 GitHub Actions 中Prepare release PR工作流的入口其决策逻辑在 scripts/prepare-release-pr.pyif 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/下是否存在*.feature.rst或*.breaking.rst文件scripts/prepare-release-pr.py——有特性或破坏性变更条目即为特性版本否则为纯补丁版本。这正是 changelog/ 目录中14743.feature.rst、14716.breaking.rst这类碎变化条目文件的用武之地。而版本号本身由find_next_version()scripts/prepare-release-pr.py计算从git tag中解析所有\d.\d.\d格式的正式 tag取最大者last_version再按类型递增主版本{last_version[0] 1}.0.0即主版本号 1次版本与补丁清零特性版本{last_version[0]}.{last_version[1] 1}.0补丁版本{last_version[0]}.{last_version[1]}.{last_version[2] 1}预发布在上述结果后追加prerelease后缀如rc1。整个发布 PR 的准备过程为切出release-{version}分支 → 运行tox -e release -- {version} {template_name} {release_branch} --skip-check-linksscripts/prepare-release-pr.py→ 强推分支 → 调用gh pr create创建草稿 PRPR 正文提示维护者后续在 deploy 工作流中以version{version}参数完成最终发布。五、发布环境的完整调用链从 tox 到 release.pytox -e release对应的环境定义在 tox.ini[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格式化校验、towncrier变更日志聚合。commands最终执行 scripts/release.py其pre_release()主流程scripts/release.py依次完成announce(...)生成发布公告并更新索引即上文第三部分regen(version)运行tox -e regen通过环境变量SETUPTOOLS_SCM_PRETEND_VERSION_FOR_PYTEST指定版本号重新生成文档中内嵌的 pytest 输出示例保证文档与版本一致scripts/release.pychangelog(version, write_outTrue)调用towncrier build --yes --version {version}把 changelog/ 目录下的碎变化条目聚合进 doc/en/changelog.rstscripts/release.py——注意脚本同时还支持--draft草稿模式用于发布前预览fix_formatting()运行pre-commit run --all-files统一代码与文档格式scripts/release.pycheck_links()运行tox -e docs-checklinks检查文档链接有效性可通过--skip-check-links跳过scripts/release.py最后git commit -a -m Prepare release version {version}提交全部变更并提示推送分支、开 PR。此外仓库还提供 scripts/generate-gh-release-notes.py在 deploy 阶段用 pandoc 将 doc/en/changelog.rst 中对应版本的 RST 条目转换为 GitHub Release 所需的 Markdown 格式与发布公告互为补充。六、主版本发布实操清单综合以上源码链路一次 pytest 主版本发布以维护者视角的完整步骤如下准备分支从目标基础分支如main出发准备创建release-{x}.0.0分支运行发布准备在tox -e prepare-release-pr环境tox.ini下执行python scripts/prepare-release-pr.py {base_branch} --major脚本将自动计算下一个主版本号、选择release.major.rst模板、执行发布流程并创建草稿发布 PR人工审核确认 PR 中生成的 doc/en/announce/release-{version}.rst 格式正确、贡献者名单无误、CHANGELOG 已聚合触发部署维护者批准后在 deploy 工作流中以version{version}参数执行包将被上传至 PyPI同时发布公告并入文档站点。对于想要单步复现公告生成的场景也可以直接运行python scripts/release.py {version} release.major.rst {doc_version} --skip-check-links前提是环境中已具备git、tox、towncrier、pre-commit以及可用的 Python 环境且当前 checkout 处于正确的发布分支上scripts/release.py 的参数解析要求依次传入version、template_name、doc_version三个位置参数。七、小结scripts/release.major.rst 虽然只有 24 行却完整浓缩了 pytest 主版本公告的固定信息架构标题、宣告、CHANGELOG 与文档引导、升级命令、贡献者致谢、统一落款。通过 scripts/release.py 的announce()注入{version}与{contributors}再经 scripts/prepare-release-pr.py 按版本类型自动选择模板最终由tox -e release环境串联起公告生成、文档重生成、CHANGELOG 聚合、格式修复与链接检查形成一条高度自动化、可审计的主版本发布流水线。理解这条流水线不仅能看懂 pytest 仓库中每一篇doc/en/announce/release-*.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 主版本发布公告模板全解：从 release.major.rst 看 pytest 的版本发布流水线
pytest 主版本发布公告模板全解从 release.major.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 仓库中的主版本发布公告模板 scripts/release.major.rst 为核心完整拆解该模板的每一处结构与占位符并结合仓库内的发布脚本scripts/release.py、scripts/prepare-release-pr.py与 tox 发布环境tox.ini还原一条从模板填充到发布 PR再到PyPI 部署的完整流水线。读完本文你将理解 pytest 主版本公告major release announcement是如何被自动生成的、它与 minor / patch / prerelease 公告模板有何区别以及维护者手动触发一次主版本发布所需的全部步骤与命令。一、模板定位主版本发布公告的唯一骨架在 pytest 仓库中scripts/目录存放着发布相关的全部脚本与模板。其中release.major.rst是主版本major发布公告专用的 reStructuredTextRST模板全文仅 24 行却是整个发布流程中文档侧的骨架它本身不包含任何版本号或贡献者姓名而是以{version}、{contributors}两个占位符等待发布脚本注入真实数据最终生成doc/en/announce/release-{version}.rst发布公告文件。与该模板并列的还有三个同族模板共同构成 pytest 四类发布公告的模板体系模板文件适用发布类型核心措辞scripts/release.major.rst主版本如 8.0.0、9.0.0proud to announce提示包含新特性、改进、bug 修复与破坏性变更scripts/release.minor.rst次版本如 9.1.0与 major 近似强调新特性与改进scripts/release.patch.rst补丁版本如 9.1.1bug-fix release, being a drop-in replacement即插即用的修复版scripts/release.pre.rst预发布版本如 9.0.0rc1明确标注not intended for production use额外包含{doc_version}占位符四个模板中major 与 minor 的内容结构几乎一致但 major 版在 CHANGELOG 指引语句上更加郑重——因为主版本通常携带破坏性变更breaking changes需要用户仔细阅读变更日志。二、逐段解析 release.major.rst 模板结构原模板全文如下保持原貌未做删改pytest-{version} The pytest team is proud to announce the {version} release! This release contains new features, improvements, bug fixes, and breaking changes, so users are encouraged to take a look at the CHANGELOG carefully: https://docs.pytest.org/en/stable/changelog.html For complete documentation, please visit: https://docs.pytest.org/en/stable/ As usual, you can upgrade from PyPI via: pip install -U pytest Thanks to all of the contributors to this release: {contributors} Happy testing, The pytest Development Team逐块解读如下一级标题pytest-{version}发布公告文档的 H1 标题{version}被替换为完整版本号例如生成pytest-9.1.1。RST 标题下方的是 underline 标记必须与标题等长或更长Sphinx 才能正确解析标题层级。发布宣告The pytest team is proud to announce the {version} release!——标准的主版本宣告句表明这是团队正式发布。CHANGELOG 引导主版本公告特意写明该版本contains new features, improvements, bug fixes, and breaking changes并引导用户仔细阅读官方文档站点的 changelog 页面。这一句是 major 模板区别于 patch 模板bug-fix release, being a drop-in replacement的关键它暗示用户升级前需评估破坏性变更。文档入口给出官方文档总入口便于用户查阅完整文档。升级命令pip install -U pytest是用户从 PyPI 升级的标准命令。值得注意的是预发布模板 scripts/release.pre.rst 中这一命令变为pip install pytest{version}——因为预发布版本必须精确指定版本号不能使用-U通配升级否则会拉到正式版。贡献者致谢区{contributors}该占位符由发布脚本自动填充为按字母排序的* 姓名列表见下文 announce 函数。真实产物示例可参考 doc/en/announce/release-9.1.1.rst其中渲染出的贡献者列表为* Bruno Oliveira、* Ran Benita。落款Happy testing, The pytest Development Team是所有 pytest 发布公告的统一签名。三、模板如何被填充announce() 的源码级实现模板自身只是骨架真正驱动它的是 scripts/release.py 中的announce()函数scripts/release.py。该函数依次完成计算提交区间调用git describe --abbrev0 --tags取得上一个发布 tag构造{last_version}..HEAD作为提交区间用于统计本次发布以来的全部作者。统计贡献者用git log {rev_range} --format%aN收集所有提交作者Author再用git log ... --format%(trailers:keyCo-authored-by)收集协作者Co-author两者合并去重后过滤掉以[bot]结尾或名为pytest bot的自动化账号最终得到真实人类贡献者集合。模板渲染读取Path(__file__).parent.joinpath(template_name)即脚本同目录下的模板文件将贡献者集合按字母序拼接为* name列表行然后调用template_text.format(version..., contributors..., doc_version...)完成占位符注入。这解释了模板中{version}与{contributors}的来源它们与format的关键字参数一一对应。写出发布公告渲染结果写入doc/en/announce/release-{version}.rstscripts/release.py。更新公告索引读取 doc/en/announce/index.rst 的 toctree将新生成的release-{version}条目插入到以release-前缀开头的条目列表最前若已存在则跳过scripts/release.py。仓库中的 doc/en/announce/index.rst 正是这样一份按版本倒序排列的历史公告目录最新版本release-9.1.1位于列表顶部。暂存文件git add生成的公告文件为后续自动提交做准备。四、四种模板的选择逻辑prepare-release-pr.py 如何决策模板不是人工挑选的而是由 scripts/prepare-release-pr.py 依据版本类型自动决定的。该脚本是 GitHub Actions 中Prepare release PR工作流的入口其决策逻辑在 scripts/prepare-release-pr.pyif 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/下是否存在*.feature.rst或*.breaking.rst文件scripts/prepare-release-pr.py——有特性或破坏性变更条目即为特性版本否则为纯补丁版本。这正是 changelog/ 目录中14743.feature.rst、14716.breaking.rst这类碎变化条目文件的用武之地。而版本号本身由find_next_version()scripts/prepare-release-pr.py计算从git tag中解析所有\d.\d.\d格式的正式 tag取最大者last_version再按类型递增主版本{last_version[0] 1}.0.0即主版本号 1次版本与补丁清零特性版本{last_version[0]}.{last_version[1] 1}.0补丁版本{last_version[0]}.{last_version[1]}.{last_version[2] 1}预发布在上述结果后追加prerelease后缀如rc1。整个发布 PR 的准备过程为切出release-{version}分支 → 运行tox -e release -- {version} {template_name} {release_branch} --skip-check-linksscripts/prepare-release-pr.py→ 强推分支 → 调用gh pr create创建草稿 PRPR 正文提示维护者后续在 deploy 工作流中以version{version}参数完成最终发布。五、发布环境的完整调用链从 tox 到 release.pytox -e release对应的环境定义在 tox.ini[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格式化校验、towncrier变更日志聚合。commands最终执行 scripts/release.py其pre_release()主流程scripts/release.py依次完成announce(...)生成发布公告并更新索引即上文第三部分regen(version)运行tox -e regen通过环境变量SETUPTOOLS_SCM_PRETEND_VERSION_FOR_PYTEST指定版本号重新生成文档中内嵌的 pytest 输出示例保证文档与版本一致scripts/release.pychangelog(version, write_outTrue)调用towncrier build --yes --version {version}把 changelog/ 目录下的碎变化条目聚合进 doc/en/changelog.rstscripts/release.py——注意脚本同时还支持--draft草稿模式用于发布前预览fix_formatting()运行pre-commit run --all-files统一代码与文档格式scripts/release.pycheck_links()运行tox -e docs-checklinks检查文档链接有效性可通过--skip-check-links跳过scripts/release.py最后git commit -a -m Prepare release version {version}提交全部变更并提示推送分支、开 PR。此外仓库还提供 scripts/generate-gh-release-notes.py在 deploy 阶段用 pandoc 将 doc/en/changelog.rst 中对应版本的 RST 条目转换为 GitHub Release 所需的 Markdown 格式与发布公告互为补充。六、主版本发布实操清单综合以上源码链路一次 pytest 主版本发布以维护者视角的完整步骤如下准备分支从目标基础分支如main出发准备创建release-{x}.0.0分支运行发布准备在tox -e prepare-release-pr环境tox.ini下执行python scripts/prepare-release-pr.py {base_branch} --major脚本将自动计算下一个主版本号、选择release.major.rst模板、执行发布流程并创建草稿发布 PR人工审核确认 PR 中生成的 doc/en/announce/release-{version}.rst 格式正确、贡献者名单无误、CHANGELOG 已聚合触发部署维护者批准后在 deploy 工作流中以version{version}参数执行包将被上传至 PyPI同时发布公告并入文档站点。对于想要单步复现公告生成的场景也可以直接运行python scripts/release.py {version} release.major.rst {doc_version} --skip-check-links前提是环境中已具备git、tox、towncrier、pre-commit以及可用的 Python 环境且当前 checkout 处于正确的发布分支上scripts/release.py 的参数解析要求依次传入version、template_name、doc_version三个位置参数。七、小结scripts/release.major.rst 虽然只有 24 行却完整浓缩了 pytest 主版本公告的固定信息架构标题、宣告、CHANGELOG 与文档引导、升级命令、贡献者致谢、统一落款。通过 scripts/release.py 的announce()注入{version}与{contributors}再经 scripts/prepare-release-pr.py 按版本类型自动选择模板最终由tox -e release环境串联起公告生成、文档重生成、CHANGELOG 聚合、格式修复与链接检查形成一条高度自动化、可审计的主版本发布流水线。理解这条流水线不仅能看懂 pytest 仓库中每一篇doc/en/announce/release-*.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），仅供参考