NumPy 发布全流程指南：从平台支持、C API 版本追踪到二进制发行版构建

• 科学计算
• 数据分析

导读

本指南基于 NumPy 官方发布文档 doc/HOWTO_RELEASE.rst 编写，系统讲解 NumPy 二进制发行版（binary release）的构建与发布全流程：从受支持平台与工具链、OpenBLAS 链接策略，到 C API 版本追踪、towncrier 发布说明生成，再到 GitHub Releases / PyPI 上传与维护分支管理。读完本文，你将掌握 NumPy 每轮 feature release 中发布经理（release manager）必须检查的关键项，以及如何通过spin、towncrier、numpy-release仓库等工具完成一次可复现、可审计的版本发布。

本文以 doc/HOWTO_RELEASE.rst 为主体，辅以 doc/RELEASE_WALKTHROUGH.rst 的 2.4.0 实测流程、doc/BRANCH_WALKTHROUGH.rst 的建分支流程，以及 numpy/_core/meson.build 等源码级证据，对发布涉及的每个环节进行深度展开。

一、发布文档体系与信息来源

发布工作依赖四类信息源，彼此配合：

• doc/HOWTO_RELEASE.rst：本指南，给出发布所需工作的总体概览（平台、工具链、版本号追踪、发布说明）；
• doc/RELEASE_WALKTHROUGH.rst：以 NumPy 2.4.0 在 Linux 上的发布为例的分步实操，是首个使用numpy/numpy-release仓库的 feature release；
• doc/BRANCH_WALKTHROUGH.rst：新建maintenance/x.y.z维护分支时的分支操作流程；
• building-from-source文档（doc/source/building）：本地从源码构建的细节。

从仓库现状看，当前开发版本为 2.6.0.dev0（见 pyproject.toml），维护分支与发布流程同样适用于后续版本，实操命令中的版本号需替换为实际发布版本。

二、支持的平台与 Python 版本

发布经理在规划发布前，首先要明确本轮发布面向哪些平台与 Python 版本。

Python 版本策略

doc/HOWTO_RELEASE.rst 明确指出：最低支持的 Python 版本由 NEP 29 规定，但 NumPy 通常会比该最低要求多支持一段时间，以避免给下游项目造成困扰。这个"多支持多久"由发布经理酌情决定。相关规范参见 doc/neps/nep-0029-deprecation_policy.rst。

实际执行中，新增/移除 Python 版本不止改pyproject.toml一处。按 doc/RELEASE_WALKTHROUGH.rst 的说明，还需要同步修改多个配置和 CI 文件，且这些改动应通过普通 PR 合入 main 分支并按需 backport。新的 Python 版本通常在首个 RC 之后、manylinux与cibuildwheel支持该版本时开始发布对应 wheel。

各平台支持矩阵

构建产物与 CI 配置可在 .github/workflows 及numpy-release仓库的wheels.yml中找到对应实现。

三、构建工具链与线性代数后端

各平台工具链

按 doc/HOWTO_RELEASE.rst 的 Toolchains 一节：

• Linux：使用manylinux/musllinuxDocker 镜像中的默认编译器，通常是较新的 GCC；
• macOS：使用 GitHub Actions runner 镜像自带的 Apple Clang 与 Xcode；
• Windows：x86/x86-64 使用 runner 镜像上的默认 MSVC 与 Visual Studio 工具链。历史上有时需要改用较旧工具链，以避免通过静态libnpymath库给 SciPy 带来问题——具体版本号需查阅numpy-release仓库代码与 CI 日志确认。

对于从源码构建，编译器最低版本要求记录在顶层 meson.build 中（当前仓库已全面迁移到 Meson 构建系统，与 pyproject.toml 中的[tool.spin.meson]配置对应）。

OpenBLAS：wheel 的线性代数依赖

大多数 NumPy wheel 链接到由 openblas-libs 仓库提供的 OpenBLAS。发布时需要注意一个关键细节（doc/HOWTO_RELEASE.rst OpenBLAS 一节）：

wheel 内的共享对象（或 DLL）被重命名后随 wheel 一起发布，以避免与文件系统中可能存在的其他 OpenBLAS 共享对象发生命名冲突。

发布前需检查numpy-release仓库中的openblas_requirements.txt确认 OpenBLAS 版本，这属于 doc/RELEASE_WALKTHROUGH.rst 中"Prior to release"清单的一部分。此外，构建时可以配置 OpenBLAS，例如仓库提供spin config-openblas命令（见 pyproject.toml 的 spin 命令注册）。

文档构建

项目已不再构建 PDF 文档。构建 HTML 文档的需求与常规开发相同，具体步骤参见numpy/doc仓库的 README 与 doc/RELEASE_WALKTHROUGH.rst 的 step by step 说明。当前文档构建依赖项见 requirements/doc_requirements.txt。

四、发布内容与 PyPI 上传方式

发布什么

按 doc/HOWTO_RELEASE.rst 的 "What is released" 一节：

• PyPI：发布多个平台的 wheel 与一个 sdist；
• GitHub Releases：发布与 PyPI 相同的 sdist（因为 GitHub 自动生成的源码归档不完整），以及发布说明（release notes）和 changelog。

PyPI 上传：trusted publishing

在 PyPI 上创建 release 并上传 wheel 与 sdist 的过程已在 CI 中自动化，采用 PyPI 的trusted publishing（受信任发布）机制——无需在 CI 中硬编码 API token。详细操作参见numpy-release仓库 README 与 doc/RELEASE_WALKTHROUGH.rst。

作者/PR 列表生成

生成 changelog 中的作者与 PR 列表，需要 GitHub 个人访问令牌（PAT）。有了令牌后运行：

spin changelog

该命令可能依赖额外包，如gitpython和pygithub（对应依赖见 requirements/release_requirements.txt）。

五、C API 版本追踪：三处必须同步

这是发布准备中最容易出错、也最需要理解底层机制的一环。doc/HOWTO_RELEASE.rst 明确要求 C API 版本在三个位置同步追踪：

1. numpy/_core/meson.build（C_API_VERSION）
2. numpy/_core/code_generators/cversions.txt
3. numpy/_core/include/numpy/numpyconfig.h（NPY_X_Y_API_VERSION宏）

第一步：判断 API 是否变化并递增 C_API_VERSION

只有满足"任何基于当前 API 编译的代码都能与上一个已发布 NumPy 版本二进制兼容"时，API 才算未变。只要 C 结构体发生变化、或公共接口有新增，新 API 就不再向后兼容，必须递增 numpy/_core/meson.build 中的C_API_VERSION。当前仓库的值为'0x00000016'（对应 2.5.x/2.6.x 系列），文件头部注释完整记录了从 1.7.x 的0x00000008至今的版本演进史。

meson.build 中同时定义了C_ABI_VERSION = '0x02000000'（见 numpy/_core/meson.build），其语义在注释中讲得很清楚：

C_ABI_VERSION 是二进制兼容性版本号，只有在二进制兼容被破坏、扩展模块需要重新编译时才递增；C_API_VERSION 是"小版本"，只要 C-API 有变化（无论是否破坏二进制兼容）都要递增。例如在函数表末尾新增一个函数指针不会破坏二进制兼容，此时只递增 C_API_VERSION。C_ABI_VERSION 只应在 major release 时更新。

第二步：同步 cversions.txt 的 API 哈希

如果第一步递增了C_API_VERSION，或者 API 哈希发生变化，就需要更新 numpy/_core/code_generators/cversions.txt。检查方法：

python numpy/_core/cversions.py

该脚本（numpy/_core/cversions.py）通过genapi.fullapi_hash(full_api)计算当前 API 的 MD5 哈希并打印。若打印的哈希与cversions.txt中最后一个版本对应的哈希不一致，说明 API 哈希已变化。此时用合适的C_API_VERSION与哈希新增一条记录。

关键的细节处理规则（原文明确给出）：

• 若 API 版本号未变但哈希变了，需要将上一个版本的条目注释掉。典型案例：NumPy 1.9 加入了函数注解，哈希改变但 API 与 1.8 相同。该案例在 numpy/_core/code_generators/cversions.txt 中有真实历史记录：0x00000009的第一个条目被注释，并写明原因。
• 哈希是 API 变化的检查手段，但不是绝对判据（"The hash serves as a check for API changes, but it is not definitive"）。
• 第 1、2 步正确完成后，编译 release 不应出现 "API mismatch detect at the beginning of the build" 警告。

这一校验在构建时是强制执行的：meson.build 会运行code_generators/verify_c_api_version.py --api-version <C_API_VERSION>并以check: true运行（见 numpy/_core/meson.build）。numpy/_core/code_generators/verify_c_api_version.py 的实现会计算当前 API 哈希并与cversions.txt记录比对，不一致时抛出MismatchCAPIError（消息提示开发者去更新meson.build与cversions.txt）。

哈希算法本身定义在 numpy/_core/code_generators/genapi.py：fullapi_hash()将所有 API 字典中的名称与数据按序拼接后计算 MD5；get_versions_hash()则用正则VERRE = r'(^0x[\da-f]{8})\s*=\s*([\da-f]{32})'解析cversions.txt（见 numpy/_core/code_generators/genapi.py）。

第三步：更新 numpyconfig.h 的 NPY_X_Y_API_VERSION

numpy/_core/include/numpy/numpyconfig.h 需要新增NPY_X_Y_API_VERSION宏，其中 X、Y 是发布版本的主、次版本号。该宏的值仅当 include 文件中某些函数或宏被弃用（deprecated）时才需要相对上一版本递增。

当前仓库中该文件的宏演进（numpy/_core/include/numpy/numpyconfig.h）展示了典型模式：多个小版本可共享同一数值（如NPY_2_1_API_VERSION与NPY_2_2_API_VERSION同为0x00000013），只有 API 实际变化时数值才前进。

建分支时的 C 版本同步

doc/BRANCH_WALKTHROUGH.rst 还补充了一个容易被忽略的场景：在准备 main 分支进入下一轮开发时，也需要更新cversions.txt以添加当前发布版本——此时通常没有新哈希需要处理，只需照此前惯例加一条注释记录即可。

六、发布说明与 changelog：towncrier 与 spin 工具

用 towncrier 聚合发布说明

doc/HOWTO_RELEASE.rst 明确使用towncrier构建发布说明并提交：

towncrier build --version "<version>" git commit -m"Create release note"

执行后，towncrier会移除 doc/release/upcoming_changes 目录下的所有 news fragment，并生成doc/release/<version>-note.rst。当前仓库的upcoming_changes目录里可见大量按<PR号>.<类型>.rst命名的片段文件（如28574.new_feature.rst、31364.c_api.rst、31387.expired.rst），[tool.towncrier]配置在 pyproject.toml 中定义，其类型覆盖 new_feature、improvement、change、performance、c_api、expired 等类别，输出文件为doc/source/release/notes-towncrier.rst。

需要说明的是：仓库中的 pyproject.toml 当前直接配置了[tool.towncrier]，而 doc/RELEASE_WALKTHROUGH.rst 中 2.4.0 流程使用的是spin notes命令（在 pyproject.toml 中注册，内部同样整合 towncrier 逻辑）。两种方式对应不同发布周期的实践，具体以发布时维护分支的配置为准。

检查与润色发布说明

发布说明需检查是否更新到位，并补充Highlights（亮点）章节，通常涵盖：

• 主要新特性（major new features）
• 已弃用与已移除的特性（deprecated and removed features）
• 支持的 Python 版本
• 对 SciPy 而言，支持的 NumPy 版本
• 近期展望（outlook for the near future）

发布说明模板位于 doc/source/release/template.rst，已发布的说明存放在 doc/source/release（如 2.0 以来的各版本 notes），changelog 则在 doc/changelog（如2.5.3-changelog.rst）。

七、发布流程总览（结合 2.4.0 实操）

doc/HOWTO_RELEASE.rst 的 "Release process" 一节给出了通用骨架，doc/RELEASE_WALKTHROUGH.rst 则提供了 Linux 上的 2.4.0 全流程实测。以下按阶段展开。

7.1 商定发布计划

典型 feature release 节奏是：两个 release candidate（RC）+ 一个正式版。发布时间应先在邮件列表上讨论，确保贡献者及时合入提交。日期确定后：

1. 创建新的maintenance/x.y.z分支；
2. 在 main 分支添加下一版本的空白发布说明；
3. 更新 issue 跟踪器上的 Milestones。

7.2 建分支（Branching）

doc/BRANCH_WALKTHROUGH.rst 给出了建分支的具体命令序列（以 2.3.x / 2.4.0 为例）：

# 开始新一轮开发周期：main 分支打注解标签 git checkout main git pull upstream main git commit --allow-empty -m'REL: Begin NumPy 2.4.0 development' git push upstream HEAD # 若因新 PR 合入导致推送失败，先 rebase 再重试 git pull --rebase upstream # 打开发起点标签 git tag -a -s v2.4.0.dev0 -m'Begin NumPy 2.4.0 development' git push upstream v2.4.0.dev0 # 创建维护分支（指向 HEAD 的父提交） git branch maintenance/2.3.x HEAD^ git push upstream maintenance/2.3.x

随后准备 main 分支继续开发：删除发布说明片段、用template.rst创建新版本发布说明骨架并加入 doc/source/release.rst 索引、按上文第五节同步cversions.txt，最后以REL: Prepare main for ...提交并开 PR。

7.3 检查弃用项

在创建 release 分支前（原文标注为:ref:branching之前）应完成检查：

• 所有应移除的已弃用代码确实被移除；
• 所有新弃用项在 docstring 或弃用警告中明确写出该代码将在哪个版本移除。

7.4 发布 PR 内容

发布 PR 通常需要更新或创建四类文档（doc/RELEASE_WALKTHROUGH.rst "Make a release PR"）：

• changelog
• release notes
• .mailmap文件
• pyproject.toml（设置发布版本号并视需要更新 classifier）

典型提交信息：

REL: Prepare for the NumPy 2.4.0 release - Create 2.4.0-changelog.rst. - Update 2.4.0-notes.rst. - Update .mailmap. - Update pyproject.toml

changelog 由spin changelog生成，它收集已合并的 PR 并格式化为可发布的 changelog：

spin changelog $GITHUB v2.3.0..maintenance/2.4.x > doc/changelog/2.4.0-changelog.rst

其中GITHUB是你的 GitHub 访问令牌。生成文本需要检查非标准贡献者名（通过更新.mailmap修正），PR 标题中的链接建议改为等宽文本（对 Markdown 不友好）。

7.5 正式发布八步走

doc/RELEASE_WALKTHROUGH.rst 将正式发布分为 8 步（以下upstream指 GitHub 上的 numpy 主仓库，origin指个人 fork）：

1. 给发布提交打标签

git checkout maintenance/2.4.x git pull upstream maintenance/2.4.x git submodule update git clean -xdfq python3 -m spin test -m full # sanity check git tag -a -s v2.4.0 -m"NumPy 2.4.0 release" git push upstream v2.4.0

如需删除错误标签：git tag -d v2.4.0与git push --delete upstream v2.4.0。

2. 构建 wheel 与 sdist

在numpy-release仓库浏览器中手动触发maintenance/2.4.x分支上的 workflow（Actions 页面点Run workflow），environment 下拉框选择pypi作为上传目标。wheel 构建约需 1 小时。若有无关原因导致的构建失败，可在 GitHub Actions UI 中re-run failed。构建完成后检查产物数量与 wheel 命名是否符合预期，再触发上传。

3. 上传 GitHub Releases

• 打开v2.4.0标签并编辑，标题改为 "v2.4.0 ( )"；
• 将发布说明从 rst 转为 markdown：python tools/write_release.py 2.4.0（生成可编辑的release/README.md，该脚本位于 tools/write_release.py），检查换行与链接后粘贴进文本窗口；
• 从 PyPI 下载 sdist（numpy-2.4.0.tar.gz）以二进制方式上传（不能用 pip 完成）；
• 以二进制方式上传release/README.rst与doc/changelog/2.4.0-changelog.rst；
• 预发布勾选 pre-release 复选框，最后点Publish release。

重要提示：确保 3 个文件齐全、发布文本完整。Releases 被配置为不可变（immutable），出错后很难再修复。

4. 上传文档到 numpy.org（预发布跳过）

需要 GitHub PAT。make merge-doc/python -m spin docs merge-doc --build会克隆numpy/doc仓库到doc/build/merge并更新新文档。若需要可再构建 PDF。新系列首次发布时需在index.html的 "insert here" 注释后添加新章节，更新_static/versions.json中的版本切换器（标记(stable)与preferred），运行python3 update.py，更新 stable 软链（ln -sfn 2.5 stable），最后提交并推送。

5. 将维护分支重置为开发状态（预发布跳过）

git checkout -b begin-2.4.1 maintenance/2.4.x cp doc/source/release/template.rst doc/source/release/2.4.1-notes.rst gvim doc/source/release/2.4.1-notes.rst # 设置版本 git add doc/source/release/2.4.1-notes.rst gvim doc/source/release.rst # 添加新发布说明链接 gvim pyproject.toml # 更新 version git commit -a -m"MAINT: Prepare 2.4.x for further development" git rebase -i HEAD^ git push origin HEAD

提交信息中添加[skip actions]行，然后开 PR 快速合入。

6. 在 numpy.org 发布公告（预发布跳过）

forknumpy/numpy.org后新建分支，编辑content/en/news.md：所有版本在页面底部加一行链接；*.0系列版本还需在顶部新增特性描述章节、更新 newsHeader/date 字段以及content/en/config.yaml中的 buttonText。提交后开 PR。

7. 邮件列表公告

发布需在 numpy-discussion 与 python-announce-list 邮件列表公告，参考以往公告模板；若交叉发布，务必对 python-announce-list 使用BCC，避免回复误发到该列表。

8. 发布后同步 main（预发布跳过）

将发布说明与 changelog 前向移植回 main 分支：

git checkout -b post-2.4.0-release-update main git checkout maintenance/2.4.x doc/source/release/2.4.0-notes.rst git checkout maintenance/2.4.x doc/changelog/2.4.0-changelog.rst git checkout maintenance/2.4.x .mailmap # 仅当发布时更新过 gvim doc/source/release.rst # 添加新说明链接 git status git commit -a -m"MAINT: Update main after 2.4.0 release." git push origin HEAD

八、发布前检查清单速查

将上述流程浓缩为发布前检查清单，便于发布经理逐项核对：

1. 邮件列表已商定发布日期；RC 计划（通常两个 RC + 正式版）已确定；
2. 已创建maintenance/x.y.z分支；main 分支已有下一版本空发布说明并更新 Milestones；
3. 已移除应移除的弃用代码；新弃用项注明移除版本；
4. C API 版本三处同步：C_API_VERSION（numpy/_core/meson.build）、cversions.txt哈希（numpy/_core/code_generators/cversions.txt）、NPY_X_Y_API_VERSION（numpy/_core/include/numpy/numpyconfig.h）；编译无 "API mismatch" 警告；
5. 运行towncrier build --version "<version>"生成并提交发布说明，补写 Highlights 章节；
6. 生成并人工检查 changelog（spin changelog），更新.mailmap；
7. 检查numpy-release仓库的 cibuildwheel 版本与openblas_requirements.txt；
8. 发布 PR 合入维护分支（changelog、notes、.mailmap、pyproject.toml）；
9. 打签标签 → 构建 wheel/sdist → 上传 PyPI（trusted publishing）→ 上传 GitHub Releases（sdist + README + changelog）；
10. 上传文档至 numpy.org、重置维护分支为开发状态、发布公告、将文档同步回 main。

总结

NumPy 的发布流程是典型的"规范化、可审计"开源项目发布范式：平台与 Python 版本策略遵循 NEP 29 并保留缓冲；构建统一走 Meson 与 CI（cibuildwheel / GitHub Actions）；C API 版本以"版本号 + MD5 哈希"双保险追踪，并由verify_c_api_version.py在构建期强制校验；发布说明由 towncrier 从 news fragment 聚合；上传 PyPI 采用 trusted publishing 自动化。掌握 doc/HOWTO_RELEASE.rst 及其配套的 doc/RELEASE_WALKTHROUGH.rst 与 doc/BRANCH_WALKTHROUGH.rst，即可完整复现一次 NumPy 版本发布，也可将此流程模式迁移到其他 Python 科学计算项目的发布工程中。

• 科学计算
• 数据分析