发布版本#

以下指南包含有关如何准备 NumPy 版本发布的详细信息。

如何准备发布#

这些说明概述了构建 NumPy 二进制发布版本所需的内容。

当前构建和发布信息#

在文档的从源代码构建部分以及这三个文件中可以找到有用的信息

支持的平台和版本#

NEP 29 概述了最低限度支持哪些 Python 版本。我们通常决定比最低要求支持更长一段时间的某个 Python 版本，以避免给其他项目带来问题 - 这由发布经理酌情决定。

macOS

我们旨在支持与 Python.org 和 cibuildwheel 为任何给定 Python 版本支持的 macOS 版本集相同的集。我们为 macOS 构建二进制 wheel，这些 wheel 与常见的 Python 安装方法兼容，例如从 python.org、python-build-standalone（uv 安装的那些）、系统 Python、conda-forge、Homebrew 和 MacPorts。
Windows

我们在 Windows 上构建 32 位和 64 位 wheel。支持 Windows 7、8 和 10。我们使用最方便的编译器构建 NumPy，这些编译器是（截至 2025 年 8 月）x86/x86-64 的 MSVC 和 arm64 的 Clang-cl，cibuildwheel 和 GitHub Actions。

Linux

我们在 PyPI 上为 x86_64 和 aarch64 平台构建和分发 manylinux 和 musllinux wheel。目前不提供 32 位平台的 wheel。我们旨在支持最低的非 EOL 版本，并大致与 cibuildwheel 同步升级。有关更多详细信息，请参阅 pypa/manylinux 和此发行版兼容性表。
BSD / Solaris / AIX

PyPI 上不提供二进制 wheel，但我们预计在这些平台上从源代码构建将正常工作。

工具链#

用于构建 wheel，我们使用以下工具链

Linux：我们在 manylinux/musllinux Docker 镜像中使用默认编译器，通常是相对较新的 GCC 版本。
macOS：我们使用 GitHub Actions 运行器镜像上安装的 Apple Clang 编译器和 XCode 版本。
Windows：对于 x86 和 x86-64，我们使用相关 GitHub Actions 运行器镜像上安装的默认 MSVC 和 Visual Studio 工具链。请注意，过去有时有必要使用旧的工具链，以避免因 SciPy 的静态 libnpymath 库而导致问题 - 请检查 numpy/numpy-release 代码和 CI 日志，以防需要确定确切的版本号。

对于从源代码构建，最低编译器版本在顶层 meson.build 文件中进行跟踪。

OpenBLAS#

大多数 wheel 都链接到通过 openblas-libs 仓库提供的 OpenBLAS 版本。共享对象（或 DLL）包含在 wheel 中，重命名以防止与文件系统中可能存在的其他 OpenBLAS 共享对象发生名称冲突。

构建文档#

我们不再构建 pdf 文件。构建 html 文档的要求与常规开发的要求没有区别。有关更多详细信息，请参阅 numpy/doc 仓库的 README 以及 doc/RELEASE_WALKTHROUGH.rst 中的分步说明。

上传到 PyPI#

在 CI 中，使用 PyPI 的受信任发布自动创建 PyPI 上的发布并上传 wheel 和 sdist。有关更多详细信息，请参阅 numpy/numpy-release 仓库的 README 以及 doc/RELEASE_WALKTHROUGH.rst 中的分步说明。

生成作者/PR 列表#

您需要一个个人访问令牌https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/，以便脚本可以访问 GitHub NumPy 仓库。使用该令牌，可以通过运行 spin changelog 来生成作者/PR 更新日志内容。它可能需要一些额外的包，例如 gitpython 和 pygithub。

发布内容#

在 PyPI 上，我们发布了适用于多个平台（如上文讨论）的 wheel 以及一个 sdist。

在 GitHub Releases 上，我们发布相同的 sdist（因为 GitHub 本身自动生成的源存档不完整），以及发布说明和更新日志。

发布流程#

确定发布时间表#

一个典型的功能发布时间表是两个候选发布和一个最终发布。最好先在邮件列表上讨论时间安排，以便大家及时提交他们的提交。确定日期后，创建一个新的 maintenance/x.y.z 分支，在主分支中为下一个版本添加新的空发布说明，并更新问题跟踪器上的里程碑。

检查弃用项#

在创建发布分支之前，应检查所有应删除的已弃用代码是否已实际删除，并且所有新的弃用项在其文档字符串或弃用警告中都说明了代码将在哪个版本被移除。

检查 C API 版本号#

C API 版本需要在三个地方进行跟踪

numpy/_core/meson.build
numpy/_core/code_generators/cversions.txt
numpy/_core/include/numpy/numpyconfig.h

该过程分为三个步骤。

如果 API 已更改，请在 numpy/core/meson.build 中增加 C_API_VERSION。仅当使用当前 API 编译的代码与上一个发布的 NumPy 版本向后兼容时，API 才未更改。任何对 C 结构体的更改或对公共接口的添加都会导致新 API 不向后兼容。
如果第一步中的 C_API_VERSION 已更改，或者 API 的哈希值已更改，则需要更新 cversions.txt 文件。要检查哈希值，请运行脚本 numpy/_core/cversions.py 并记下打印出的 API 哈希值。如果该哈希值与 numpy/_core/code_generators/cversions.txt 中的最后一个哈希值不匹配，则表示哈希值已更改。同时使用适当的 C_API_VERSION 和哈希值，向 cversions.txt 添加新条目。如果未更改 API 版本，但哈希值不同，则需要注释掉该 API 版本的先前条目。例如，在 NumPy 1.9 中添加了注解，这改变了哈希值，但 API 与 1.8 相同。哈希值用于检查 API 更改，但并非决定性。

如果步骤 1 和 2 执行正确，编译发布版时不应出现“在构建开始时检测到 API 不匹配”的警告。
numpy/_core/include/numpy/numpyconfig.h 将需要一个新的 NPY_X_Y_API_VERSION 宏，其中 X 和 Y 是发布的 major 和 minor 版本号。如果包含文件中的某些函数或宏已被弃用，则需要将赋予该宏的值从前一个版本增加。

numpy/_core/meson.build 中的 C ABI 版本号仅应为主版本发布更新。

检查发布说明#

使用 towncrier 来构建发布说明并提交更改。这将从 doc/release/upcoming_changes 中删除所有片段，并添加 doc/release/<version>-note.rst。

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

检查发布说明是否是最新的。

更新发布说明，添加一个“亮点”部分。提及以下内容中的一些

主要新功能
已弃用和已移除的功能
支持的 Python 版本
对于 SciPy，支持的 NumPy 版本
近期展望

分步指南#

这是在 Linux 上进行 NumPy 2.4.0 发布演练，这将是第一个使用 numpy/numpy-release 仓库的功能发布。

可以将命令复制到命令行中，但请确保将 2.4.0 替换为正确的版本。这应与通用发布指南一起阅读。

设施准备#

在开始发布之前，使用 requirements/*_requirements.txt 文件来确保您拥有所需的软件。大多数软件都可以用 pip 安装，但有些需要 apt-get、dnf 或您的系统使用的任何软件安装程序。您还需要一个 GitHub 个人访问令牌（PAT）来推送文档。有几种方法可以简化事情

Git 可以设置为使用密钥环来存储您的 GitHub 个人访问令牌。在线搜索详细信息。
您可以使用 keyring 应用程序来存储 twine 的 PyPI 密码。有关详细信息，请参阅在线 twine 文档。

发布前#

添加/删除 Python 版本#

添加或删除 Python 版本时，除了更改 pyproject.toml 中的最低版本外，还需要编辑多个配置文件和 CI 文件。在针对 main 的常规 PR 中进行这些更改，并在必要时进行回溯。我们目前在 manylinux 和 cibuildwheel 支持新 Python 版本后，在第一个 Python RC 发布后发布新 Python 版本的 wheel。

回溯拉取请求#

已标记为此版本更改的内容必须回溯到 maintenance/2.4.x 分支。

更新 2.4.0 里程碑#

查看带有 2.4.0 里程碑的 issue/pr，然后将其推迟到稍后的版本，或者可能删除里程碑。您可能需要添加一个里程碑。

检查 numpy-release 仓库#

要检查的内容是 .github/workflows/wheels.yml 中的 cibuildwheel 版本以及 openblas_requirements.txt 中的 openblas 版本。

创建发布 PR#

发布 PR 通常需要更新或创建四个文档

更新日志
发布说明
`.mailmap` 文件
`.pyproject.toml` 文件

这些更改应在针对维护分支的常规 PR 中进行。其他小的、杂项的修复可能属于此 PR。提交消息可能类似于

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

设置发布版本#

检查 pyproject.toml 文件并设置发布版本以及在需要时更新分类器

$ gvim pyproject.toml

检查 `doc/source/release.rst` 文件#

确保发布说明在 release.rst 文件中有条目

$ gvim doc/source/release.rst

生成更新日志#

更新日志使用更新日志工具生成

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

其中 GITHUB 包含您的 GitHub 访问令牌。文本需要检查非标准贡献者姓名。将 PR 标题中的任何链接替换为等宽文本也是个好主意，因为它们不容易翻译成 Markdown。非标准贡献者姓名应通过更新 .mailmap 文件来修复，这需要大量工作。最好在达到这一点之前进行多次试运行，并使用 GitHub issue ping 相关人员以获取所需信息。

完成发布说明#

如果 doc/release/upcoming_changes/ 中有任何发布说明片段，请运行 spin notes，它会将片段合并到 doc/source/release/notes-towncrier.rst 文件中并删除片段。

$ spin notes
$ gvim doc/source/release/notes-towncrier.rst doc/source/release/2.4.0-notes.rst

一旦 notes-towncrier 的内容已合并到发布说明中，就可以删除 .. include:: notes-towncrier.rst 指令。说明总需要一些修复，引言需要编写，并且应突出显示重大更改。对于补丁发布，也可以附加更新日志文本，但对于初始发布则不行，因为它太长了。请查看之前的发布说明了解如何执行此操作。

测试 wheel 构建#

发布 PR 合并后，在浏览器中转到 numpy-release 仓库，然后在 actions 中使用 Run workflow 按钮在 maintenance/2.4.x 分支上手动触发工作流。确保在环境下拉菜单中上传目标为 none。wheel 构建大约需要 1 小时，但有时 GitHub 会非常慢。如果某些 wheel 构建因无关原因失败，您可以像平常一样在 GitHub Actions UI 中使用 re-run failed 重新运行它们。构建完 wheel 后，请查看结果，检查工件数量是否正确，wheel 名称是否符合预期等。如果一切看起来都很好，则继续进行发布。

发布演练#

请注意，在下面的代码片段中，upstream 指的是 GitHub 上的根仓库，origin 指的是您个人 GitHub 仓库中的 fork。如果您没有 fork 仓库而只是本地克隆了它，则可能需要进行调整。您也可以编辑 .git/config 并添加 upstream（如果它尚不存在）。

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

标记发布并推送标签。这需要对 numpy 仓库的写入权限

$ 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 仓库，然后在 actions 中使用 Run workflow 按钮在 maintenance/2.4.x 分支上手动触发工作流。确保在环境下拉菜单中上传目标为 pypi。wheel 构建大约需要 1 小时，但有时 GitHub 会非常慢。如果某些 wheel 构建因无关原因失败，您可以像平常一样在 GitHub Actions UI 中使用 re-run failed 重新运行它们。构建完 wheel 后，请查看结果，检查工件数量是否正确，wheel 名称是否符合预期等。如果一切看起来都很好，则触发上传。

3. 上传文件到 GitHub Releases#

转到 numpy/numpy，应该有一个 v2.4.0 标签，点击它并点击该标签的编辑按钮，将标题更新为“v2.4.0 (<date>)”。有两种添加文件的方式：使用可编辑文本窗口和作为二进制上传。文本窗口需要 markdown，因此将发布说明从 rst 转换为 md

$ python tools/write_release.py 2.4.0

这将创建一个 release/README.md 文件供您编辑。检查结果以确保其看起来正确。可能需要修复的内容：需要取消换行的换行符以及应更改为等宽文本的链接。然后将内容复制到剪贴板并粘贴到文本窗口中。可能需要几次尝试才能使其看起来正确。然后

从 PyPI 下载 sdist（numpy-2.4.0.tar.gz）并将其作为二进制文件上传到 GitHub。您无法使用 pip 完成此操作。
将 release/README.rst 作为二进制文件上传。
将 doc/changelog/2.4.0-changelog.rst 作为二进制文件上传。
如果这是预发布版，请勾选预发布按钮。
点击底部的 Publish release 按钮。

注意

请确保所有 3 个上传的文件都存在且发布文本完整。发布被配置为不可变的，因此错误（轻易地）无法修复。

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

注意

您将需要一个 GitHub 个人访问令牌来推送更新。

此步骤仅对最终发布是必需的，可以跳过预发布版和大多数补丁发布。 make merge-doc 将 numpy/doc 仓库克隆到 doc/build/merge 中，并用新文档更新它。

$ git clean -xdfq
$ git co v2.4.0
$ rm -rf doc/build  # want version to be current
$ python -m spin docs merge-doc --build
$ pushd doc/build/merge

如果发布系列是新的，您需要在 doc/build/merge/index.html 主页的“在此处插入”注释之后添加一个新部分。

$ gvim index.html +/'insert here'

此外，更新版本切换器 JSON 文件以添加新发布，并更新标记为 (stable) 和 preferred 的版本。

$ gvim _static/versions.json

然后运行 update.py 来更新 _static 中的版本。

$ python3 update.py

您可以在浏览器中“试运行”新文档，以确保链接正常工作，尽管版本下拉菜单不会更改，因为它从 numpy.org 获取信息。

$ firefox index.html  # or google-chrome, etc.

更新稳定链接并更新

$ ln -sfn 2.4 stable
$ ls -l  # check the link

一旦一切看起来都令人满意，则更新、提交并上传更改。

$ git commit -a -m"Add documentation for v2.4.0"
$ git push [email protected]:numpy/doc
$ popd

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

更新 pyproject.toml 中的 version。

$ gvim pyproject.toml

提交结果，编辑提交消息，记下提交中的文件，并添加一行 [skip cirrus] [skip actions]，然后推送。

$ git commit -a -m"MAINT: Prepare 2.4.x for further development"
$ git rebase -i HEAD^
$ git push origin HEAD

转到 GitHub 创建 PR。它应该很快被合并。

6. 在 numpy.org 上宣布发布（预发布版跳过）#

这假定您已经 fork 了 numpy/numpy.org。

$ cd ../numpy.org
$ git checkout main
$ git pull upstream main
$ git checkout -b announce-numpy-2.4.0
$ gvim content/en/news.md

对于所有发布，请转到页面底部并添加一行链接。参考之前的链接作为示例。
对于周期中的 *.0 版本，在顶部添加一个新部分，简要描述新功能，并将新闻链接指向它。
编辑 news.md 开头的 newsHeader 和 date 字段。
同时编辑 content/en/config.yaml 第 14 行的 buttonText。

提交并推送。

$ git commit -a -m"announce the NumPy 2.4.0 release"
$ git push origin HEAD

转到 GitHub 创建 PR。

7. 在邮件列表中宣布#

应在 numpy-discussion 和 python-announce-list 邮件列表中宣布此发布。参考之前的公告以获取基本模板。贡献者和 PR 列表与上面为发布说明生成的相同。如果您交叉发布，请确保 python-announce-list 是密送，以便回复不会发送到该列表。

8. 发布后更新 main（预发布版跳过）#

签出 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  # only if updated for release.
$ gvim doc/source/release.rst  # Add link to new notes
$ git status  # check status before commit
$ git commit -a -m"MAINT: Update main after 2.4.0 release."
$ git push origin HEAD