Hypothesis 的 RELEASE.rst 发布说明机制：从补丁记录到版本发布的完整工作流

测试开发工具【免费下载链接】hypothesisThe property-based testing library for Python项目地址https://gitcode.com/gh_mirrors/hy/hypothesis点击查看免费下载导读Hypothesis 是 Python 生态中最具影响力的 property-based testing属性测试库其每个版本的发布都依赖一个位于 hypothesis/RELEASE.rst 的发布说明文件作为唯一事实来源贡献者只需在该文件中写入一行版本类型与一段变更说明合并后即可由自动化工具链自动完成版本号递增、changelog 追加、Rust 核心同步、文档构建乃至 PyPI 发布的全流程。本文将深入剖析这个文件的格式规范、解析规则与自动化发布流水线帮助读者理解并复刻 Hypothesis 的发布工程实践。一、RELEASE.rst 是什么一份可被机器解析的发布说明1.1 文件的位置与作用在仓库根目录 hypothesis/RELEASE.rst 下存在一个特殊文件——它不是普通的 changelog 条目而是下一次发布候选的发布说明。当前仓库中的实际内容只有两行RELEASE_TYPE: patch We now publish abi3 wheels for Linux s390x (manylinux) and Linux i686 (musllinux).这个文件的定位可以从两处源码得到印证tooling/src/hypothesistooling/release.py 中RELEASE_FILE HYPOTHESIS / RELEASE.rst与RELEASE_SAMPLE_FILE HYPOTHESIS / RELEASE-sample.rst表明它是发布工具链的直接输入文档构建配置 hypothesis/docs/changelog.rst 通过 Sphinx 的.. include:: ../RELEASE.rst指令在文档的 Current pull request 栏目中动态内嵌该文件的内容使未发布的变更在文档站点上即可预览。1.2 为什么用 RELEASE.rst 而不是直接改 changelog传统项目通常在发布时集中整理 changelog而 Hypothesis 采取变更即记录的模式每个 PR 自带发布说明只要有源码改动就必须伴随一个 RELEASE.rst由 CI 强制检查见下文 §4.1发布时自动合并发布脚本将 RELEASE.rst 的内容自动写入 hypothesis/docs/changelog.rst 顶部形成永久记录文件即契约发布类型major/minor/patch决定版本号如何递增机器据此自动计算新版本号。二、RELEASE.rst 的格式规范与解析规则2.1 文件结构两段式RELEASE.rst 由且仅由两部分组成第一行RELEASE_TYPE:后跟major、minor、patch三选一其余行本次发布的 changelog 正文RST 格式的纯文本描述。2.2 机器解析的严格规则解析逻辑位于 tooling/src/hypothesistooling/release.py规则如下文件第一行必须匹配正则^RELEASE_TYPE: (major|minor|patch)类型必须是major、minor、patch之一VALID_RELEASE_TYPES元组定义了合法取值解析成功后第一行会被删除剩余内容.strip()后作为 changelog 正文若第一行不匹配会抛出ValueError并提示正确写法The first line of the file should be RELEASE_TYPE: followed by one of major, minor, or patch。2.3 三种发布类型的语义以 RELEASE-sample.rst 中的官方说明为准类型触发条件版本号变化patch常规修复、内部改动第三位 1如 6.167.1 → 6.168.0 的补丁位minor公共 API 有可见变化新增功能等第二位 1major存在破坏性变更第一位 1注意sample 文件明确指出只有维护者maintainers才应该进行 major 发布普通贡献者提交的 PR 不应自行声明 major。版本号递增的底层实现在 release.py 的bump_version_info()按VALID_RELEASE_TYPES.index(release_type)定位要递增的位然后将该位之后的位数全部清零——这正是语义化版本SemVer的标准行为。三、如何撰写一份合格的发布说明3.1 从模板开始RELEASE-sample.rst仓库提供了官方模板 hypothesis/RELEASE-sample.rst贡献者应复制它到 RELEASE.rst而非移动CI 会检查模板仍存在并填写真实内容。模板中Thanks to contributors name or handle 是给维护者的致谢占位符由发布流程保留。3.2 正文写作规范模板原文要求简洁描述公共 API 的变化及原因聚焦对用户可见的部分仅内部改动可写为如 This release improves an internal invariant.这正是版本 6.99.11 的真实 changelog使用双反引号包裹代码如double backticks使用 Sphinx 交叉引用来指向函数、类、issue、PR 与文档章节例如:func:package.function链接文字为 package.function:func:~package.function则只显示function:class:package.class 用于类:issue:issue-number 引用 GitHub issue:pull:pr-number引用 PR但官方更推荐用 :v:6.98.9引用版本号因为它对最终用户更有意义:doc:链接文字 chapter#anchor 引用文档章节一般网页地址用链接文字 https://...__ 形式结尾附上维护者的致谢如果是首次贡献记得把自己加入 AUTHORS.rst。3.3 真实案例对照当前 RELEASE.rst 就是一份极简的合格示例而 changelog.rst 顶部的 6.168.0 条目展示了完整写法——既描述了datetimes策略在时区切换、闰秒等刁钻时刻生成行为的改进也记录了内部缓存错误的修复并使用了:func:与:issue:引用。写作时对照 changelog 的历史条目可以快速掌握措辞风格。四、RELEASE.rst 的自动化生命周期4.1 CI 强制校验没有 RELEASE.rst 就无法合并仓库测试 whole_repo_tests/whole_repo/test_release_files.py 实现了三条硬性约束存在性校验只要src/目录有源码变更release.has_source_changes()就必须存在 RELEASE.rst否则报错 There are source changes but no RELEASE.rst. Please create one...模板完整性RELEASE-sample.rst 必须仍然存在Please copy it to RELEASE.rst, rather than moving it格式校验release.parse_release_file()会按 §2.2 的规则解析格式错误直接测试失败。同文件的 test_release_file_has_no_merge_conflicts 还防止两类低级错误检测合并冲突残留检查本次发布说明与最近 12 个历史 changelog 条目既不重复也不互相包含避免重复发布或从历史条目复制粘贴导致的合并错误。4.2 自动生成的补丁说明对于纯自动化改动如升级依赖、刷新时区数据工具链会自动生成发布说明。在 tooling/src/hypothesistooling/main.py 中upgrade_requirements任务执行后若检测到源码差异且尚无 RELEASE.rst会自动写入RELEASE_TYPE: patch加一段模板化消息见 release.py 的get_autoupdate_message()——比如本次补丁更新了 vendored 的顶级域名列表用于hypothesis.provisional.domains策略。4.3 发布流水线RELEASE.rst 驱动一切发布入口publish任务tooling/src/hypothesistooling/main.py的执行链如下校验环境要求存在ACTIONS_ID_TOKEN_REQUEST_TOKENPyPI 受信发布用与GH_TOKENGitHub Release 用两个环境变量计算新版本号compute_new_version()读取 RELEASE.rst 的类型并调用bump_version_info()更新 changelog 与版本update_changelog_and_version()release.py完成核心工作解析 RELEASE.rst计算新版本号在 changelog.rst 顶部插入形如.. _v6.168.0: 分隔线 6.168.0 - 2026-09-08标题 发布正文的新条目若为 major 发布还会在 changelog 中新增Hypothesis (N-1).x的历史版本分栏同步写入 hypothesis/rust/Cargo.toml 的 Rust 核心版本并更新 Cargo.lock将源码中所有sinceRELEASEDAY占位符替换为实际发布日期用正则回写 hypothesis/pyproject.toml如把 README 内容内嵌、重算allextra 列表提交并打标签commit_pending_release()生成 Bump hypothesis version to X.Y.Z and update changelog 的提交然后创建并推送vX.Y.Z标签上传 PyPIupload_distribution_to_pypi()release.py先用正则校验 dist 目录中每个 wheel/sdist 的文件名版本号与预期一致如hypothesis-6.168.0-cp313-cp313-manylinux_2_17_x86_64.whl再用twine upload --skip-existing上传创建 GitHub Releasecreate_github_release()用 Sphinx 构建纯文本 changelog取出最新条目作为 Release 正文并通过 GitHub API 创建 Release用于触发 Zenodo DOI 铸造。值得注意的是发布文档构建任务main.py在验证完 changelog 更新后会git checkout还原 changelog、Cargo 文件——因为最终写入要等真正发布时一次性完成避免中间状态污染。五、与 changelog.rst 的协同关系hypothesis/docs/changelog.rst 是累计的历史发布记录当前已到 6.168.0共 18300 行它与 RELEASE.rst 构成临时态 → 永久态的映射写入时机PR 合并前变更只存在于 RELEASE.rst预览机制文档构建时.. include:: ../RELEASE.rst将其呈现为 Current pull request 栏目仅当构建环境启用了has_release_file标签时生效归档时机发布脚本将 RELEASE.rst 内容追加进 changelog 顶部并git rm删除该文件随后版本号递增新的一轮开发重新开始。因此读者在 changelog.rst 中看到的每个版本条目其出生地都曾是仓库根目录下的一份 RELEASE.rst。六、给贡献者的操作清单修改 hypothesis/src 下的源码后复制hypothesis/RELEASE-sample.rst 为 hypothesis/RELEASE.rst首行填写正确的发布类型普通修复写patch公共 API 新增写minor破坏性变更仅由维护者写major正文用 RST 与 Sphinx 引用描述对用户可见的变化参考 changelog.rst 顶部的最新条目风格如属首次贡献将自己的名字加入 AUTHORS.rst提交 PR等待 CI 执行 test_release_files.py 验证文件存在、格式合法、无合并冲突、不与历史条目重复PR 合并后维护者执行publish任务RELEASE.rst 的内容即自动转化为正式版本与永久 changelog 条目。七、结语一份文件驱动整个发布链Hypothesis 用一份仅两行的 RELEASE.rst 撬动了版本号计算、changelog 归档、Rust 核心同步、文档预览与 PyPI/GitHub 双端发布整条流水线。这种变更即记录、发布即归档的工程模式配合 CI 的强制校验既保证了每个贡献者都能清晰表达自己的变更也让版本发布完全可预测、可审计。对于任何希望建立规范发布流程的 Python 项目tooling/src/hypothesistooling/release.py 与配套测试都是值得直接借鉴的实现范本。赞分享测试开发工具【免费下载链接】hypothesisThe property-based testing library for Python项目地址https://gitcode.com/gh_mirrors/hy/hypothesis点击查看免费下载相关推荐构建企业级代码沙箱Judge0架构设计与实施指南构建企业级代码沙箱Judge0架构设计与实施指南 行业挑战与需求分析 在数字化转型浪潮中企业面临着代码执行需求的指数级增长。在线编程教育平台需要安全的代码运测试开发工具Argo Workflows 发布流程详解从补丁版本到特性版本的完整发布指南Argo Workflows 发布流程详解从补丁版本到特性版本的完整发布指南 导读 本文基于 Argo Workflows 官方发布指南 docs/rele云原生容器编排工作流自动化任务调度后端三步把代码库变成可交互的代码知识图谱Understand-Anything 完全指南三步把代码库变成可交互的代码知识图谱Understand Anything 完全指南 Understand Anything 是一款开源 AI 代码知识图谱工AI 技能AI 插件开发工具知识图谱上一篇如何用Sunshine搭建家庭游戏串流服务器5分钟快速入门指南下一篇Kimi Code CLI Web UI 实战指南浏览器中的 CLI Agent 交互界面与安全配置创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考