pybind11 版本发布指南从版本号规范到完整的发布流程实战【免费下载链接】pybind11Seamless operability between C11 and Python项目地址: https://gitcode.com/GitHub_Trending/py/pybind11本篇指南以 pybind11 官方文档 docs/release.rst 为骨架系统讲解 pybind11 项目的版本号规范PEP 440、源码中的版本宏定义、基于 nox 的自动化校验与打包工具链以及从打 tag、管理 stable/发布分支到最终发布 GitHub Release 与 PyPI 包的完整流程。读完本文你将掌握 pybind11 项目“如何正确发布一个新版本”的全套操作也能理解版本号为何必须以include/pybind11/detail/common.h为唯一事实来源。版本号规范必须符合 PEP 440pybind11 的版本号必须是一个合法的 PEP 440 中可以看到当前版本的全部版本宏#define PYBIND11_VERSION_MAJOR 3 #define PYBIND11_VERSION_MINOR 1 #define PYBIND11_VERSION_MICRO 0 // ALPHA 0xA, BETA 0xB, GAMMA 0xC (release candidate), FINAL 0xF (stable release) #define PYBIND11_VERSION_RELEASE_LEVEL PY_RELEASE_LEVEL_FINAL #define PYBIND11_VERSION_RELEASE_SERIAL 0 #define PYBIND11_VERSION_PATCH 0各宏的含义与规范如下宏含义取值约定PYBIND11_VERSION_MAJOR主版本号 X正整数PYBIND11_VERSION_MINOR次版本号 Y正整数PYBIND11_VERSION_MICRO补丁号 Z简单整数发布流程要求PYBIND11_VERSION_RELEASE_LEVEL发布阶段PY_RELEASE_LEVEL_ALPHA/BETA/GAMMA(RC) /FINALPYBIND11_VERSION_RELEASE_SERIAL发布序号开发版本用0xA0LEVEL0xASERIAL0稳定版固定为 0PYBIND11_VERSION_PATCH版本字符串补丁段例如0a0、0b1、0rc1最终发布必须是简单整数关于PYBIND11_VERSION_PATCH的写法文档明确规定alpha 阶段如Za0表示 Z 号版本的第一个 alphabeta 阶段应为Zb1如3.2.0b1RC 阶段可为Zrc1如3.2.0rc1最终发布必须是简单整数如3.1.0的 PATCH 为0。这些宏还会被组合成一个 4 字节十六进制版本号PYBIND11_VERSION_HEX见 include/pybind11/detail/common.h通过Py_PACK_FULL_VERSION打包用于与 Python 运行时的 API 版本做兼容判断。版本号单一事实来源Single Source of Truthinclude/pybind11/detail/common.h中的宏是版本号的唯一权威来源仓库内的其他版本信息都由它派生pybind11/_version.py 在未安装从源码直接运行时通过正则从common.h解析出__version__与version_info构建成 wheel 后该文件会被替换为写死的版本号pyproject.toml 中的[tool.scikit-build.metadata.version]也使用regexprovider 从common.h读取版本实现打包元数据与源码宏的自动同步构建时 scikit-build 会根据common.h中的版本自动生成正式版 pybind11/_version.py模板见 pyproject.toml。因此发布时只要改一处common.h就能保证 pip 元数据、pybind11.__version__和 C 头文件宏保持一致。发布前的环境准备发布流程大量使用 nox 会话。如果你没有安装 nox官方推荐以下任一方式直接使用pipx run nox无需显式安装uv tool install noxpipx install noxUnix 系统下brew install nox。发布一个新版本的完整步骤1. 更新版本号修改 include/pybind11/detail/common.h 中的PYBIND11_VERSION_MAJOR等宏其中MICRO 应为简单整数。改完后运行打包测试验证修改是否正确nox -s tests_packaging从源码看该 nox 会话会安装 tests/requirements.txt 并执行pytest tests/extra_python_package见 noxfile.py实际校验打包结果与版本号是否符合预期。2. 核对 pyproject.toml 元数据确保 pyproject.toml 中的信息保持最新例如支持的 Python 版本classifiers 中的Programming Language :: Python :: 3.x列表项目描述、作者、许可证、依赖分组等。当前仓库的 classifiers 覆盖 Python 3.9 至 3.15并声明 CPython 与 PyPy 实现requires-python 3.9。3. 更新 changelog在 docs/changelog.md 中补充发布日期并整合nox -s make_changelog的输出nox -s make_changelog这个命令的底层是 tools/make_changelog.py其工作机制值得了解它调用 GitHub API 查询所有已关闭且带有needs changelog标签的 PR/issue每页 100 条从每个条目 body 中的## Suggested changelog entry:区块提取内容格式化成本文条目并附上 PR 编号链接依据 PR 标题的 conventional commit 前缀如feat(...)、fix(...)、docs、tests、ci、chore自动归类为 New Features、Bug fixes、Documentation、Tests、CI、Other 等章节若 token 可用则使用GITHUB_TOKEN/GH_TOKEN或gh auth token获取避免公共 CDN 的过期缓存导致结果陈旧。注意make_changelog只是输出建议内容需要手动在 docs/changelog.md 中集成并且要手动在 GitHub Web 界面清除已处理条目的needs changelog标签点击文档中给出的标签链接筛选即可非常方便。4. 提交并推送确保 CI 通过git add git commit git push务必确保 CI 通过。如果失败原因是已知的 flake偶发不稳定问题可以选择忽略或重启 CI。5. 创建或更新发布分支如果是新的MINOR版本创建新的发布分支如果是patch版本则更新已有分支。文档假设你的upstream指向 pybind11 官方仓库https://github.com/pybind/pybind11.git# 新分支新 MINOR 版本 git checkout -b vX.Y git push -u upstream vX.Y # 更新分支patch 版本 git checkout vX.Y git merge release branch git push6. 更新 tags可选步骤打 annotated tag 并做最后一次一致性检查git tag -a vX.Y.Z -m vX.Y.Z release git grep PYBIND11_VERSION include/pybind11/detail/common.h # 最后一次一致性检查与 tag 是否一致 git push upstream vX.Y.Zgit grep输出中的版本宏应与 tag 名称完全一致。如果跳过此步骤也没关系后续创建 GitHub Release 时会自动为你生成一个轻量non-annotatedtag。7. 更新 stable 分支pybind11 维护一个长期指向最新稳定版的stable分支更新流程如下git checkout stable git merge -X theirs vX.Y.Z git diff vX.Y.Z # 仔细审查并调和差异理论上应无差异 git push其中-X theirs表示冲突时以被合并分支vX.Y.Z为准随后用git diff vX.Y.Z确认 stable 与发布 tag 完全一致。8. 创建 GitHub ReleaseGitHub Release 会显示在仓库 UI 中、向关注 releases 的用户发送通知同时触发 PyPI 包的上传。提供两种方式GUI 方式在仓库的 Releases 页面点击 Draft a new release填写 tag 名称若第 6 步未打 tag可在此处创建Release 名称格式为 Version X.Y.Z将Markdown 格式的 changelog 复制粘贴到描述中。可以移除多余换行也可以去掉 PR/issue 的超链接标记例如简化为裸的#1234。如果是 alpha/beta/RC 版本勾选 pre-release。CLI 方式需安装ghgh release create vX.Y.Z -t Version X.Y.Z # 预发布版本加 -p 参数 gh release create vX.Y.Z -t Version X.Y.Z -p9. 发布后回到开发状态发布完成后立即把仓库恢复到开发状态防止误在发布版本上继续开发git checkout master # 确保在 master 上然后更新 include/pybind11/detail/common.h 中的版本宏PATCH 设为0a0MINOR 递增例如 3.1.0 发布后变成 3.2.0a0同步更新 pybind11/_version.py 使其匹配再次运行nox -s tests_packaging验证修改正确如果本次发布是新的 MINOR 版本在 docs/changelog.md 中新增一个IN DEVELOPMENT章节git add、git commit、git push。版本分支的 PATCH 约定如果后续更新了某个版本分支如 vX.Y 上继续出 patch记得将 PATCH 设为1a0——这与 master 上的0a0约定相区分表示该分支已进入维护期。下游渠道的自动发布pybind11 的发布会自动传导到主流包管理器conda-forge发布后几个小时内会自动创建 PR若无问题会自动合并Homebrew同样自动更新。维护者无需手动干预这两个渠道。手动打包与上传备用方案正常情况下 GitHub Release 会自动上传 PyPI 包无需手动操作。但如果你需要手动上传发行产物可以从 CI job artifacts 下载后用 twine 上传也可以在本地构建文档不建议常规情况下这样做因为本地目录更可能不干净SDist 构建时容易把无关的隐藏文件一并打包进去。本地构建流程为nox -s build # 构建 SDist 和 wheel nox -s build_global # 构建 pybind11-global 的 SDist 和 wheel twine upload dist/* # 上传产物前两行分别构建标准包与全局包最后一行把dist/目录下的所有产物上传到 PyPI。从源码看这两个 nox 会话的行为是build安装build后执行python -m build见 noxfile.py产出 SDist 与 wheelbuild_global先运行 tools/make_global.py用 tomlkit 动态改写 pyproject.toml将项目名改为pybind11-global、移除 entry-points 与 optional-dependencies、设置wheel.install-dir /data等再执行python -m build构建完成后利用preserve_file上下文管理器恢复原始 pyproject.toml见 noxfile.py。小结pybind11 的版本发布是一套高度流程化、且由工具链强校验的工程实践其核心要点可以概括为版本号唯一来源是 include/pybind11/detail/common.h 的宏定义_version.py与 PyPI 元数据都由它自动派生每次改版本宏后必须运行nox -s tests_packaging做打包级校验tests/extra_python_package 下的测试是发布前的最后一道关卡changelog 由 tools/make_changelog.py 依据needs changelog标签与 PR 描述自动生成维护者负责集成与清理标签发布分支vX.Y、tagvX.Y.Z与stable分支三者的状态必须严格一致并用git diff/git grep做交叉校验发布结束后立即恢复 master 开发态PATCH 置0a0、MINOR 递增避免在发布版本上继续开发。对于 pybind11 的维护者而言本文即是一份可直接对照执行的发布操作手册对于希望理解该项目 CI 与打包体系的读者noxfile.py、tools/make_changelog.py 与 tools/make_global.py 则是值得深入阅读的实现参考。【免费下载链接】pybind11Seamless operability between C11 and Python项目地址: https://gitcode.com/GitHub_Trending/py/pybind11创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考