发布版本

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

如何准备发布

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

当前构建和发布信息

可以在以下位置找到有用的信息：

• 源码树

  • 安装.rst

  • 路面.py

• NumPy 文档

  • https://github.com/numpy/numpy/blob/main/doc/HOWTO_RELEASE.rst

  • https://github.com/numpy/numpy/blob/main/doc/RELEASE_WALKTHROUGH.rst

  • https://github.com/numpy/numpy/blob/main/doc/BRANCH_WALKTHROUGH.rst

• 发布脚本

  • https://github.com/numpy/numpy-vendor

支持的平台和版本

NEP 29概述了支持哪些 Python 版本； 2020 年上半年，Python >= 3.6。每次将代码合并到 main 时，我们都会针对所有这些版本测试 NumPy。二进制安装程序可能适用于这些版本的子集（见下文）。

• 操作系统

  支持 OS X 版本 >= 10.9，有关 Python 版本支持，请参阅 NEP 29。我们为 OSX 构建与 Python.org Python、Python 系统、自制程序和 macports 兼容的二进制轮 - 有关详细信息，请参阅此 OSX 轮构建摘要 。

• Windows

  我们在 Windows 上构建 32 位和 64 位轮子。支持 Windows 7、8 和 10。我们使用mingw-w64 工具链、cibuildwheels和 GitHub actions构建 NumPy 。

• Linux

  我们 为 NumPy构建并发布了许多 Linux2014轮子。许多 Linux 发行版都包含自己的 NumPy 二进制版本。

• BSD / Solaris

  未提供二进制文件，但已报告在 Solaris 和 BSD 上成功构建。

工具链

我们在云基础设施上构建所有轮子 - 因此此编译器列表用于提供信息和调试本地构建。请参阅numpywheel.travis.yml存储库中的脚本，了解使用多重构建的构建配方的过时源。

编译器

使用相同的 gcc 版本作为在每个平台上构建 Python 本身的版本。目前这意味着：

• OS X 构建于 travis 之上，目前使用clang。当从 Python.org 安装程序针对 Python 进行构建时，似乎可以从 travis-ci OSX 10.9 虚拟机安全地构建 OSX >= 10.6 的二进制轮子；

• Windows 构建使用mingw-w64 工具链；

• Manylinux2014 轮子使用 Manylinux docker 镜像上提供的 gcc。

您将需要 Cython 来构建二进制文件。 Cython 将.pyx NumPy 发行版中的文件编译为.c文件。

OpenBLAS

所有轮子都链接到通过openblas-libs存储库提供的OpenBLAS版本。共享对象（或 DLL）随轮子一起提供，并重命名以防止与文件系统中可能存在的其他 OpenBLAS 共享对象发生名称冲突。

构建源档案和轮子

NumPy 轮子和 sdist 现在使用 cibuildwheel 和 github 操作构建。

构建文档

我们不再构建 pdf 文件，而是构建 html 文档。需要numpy-html.zip 上传到文档服务器的可以使用.spin docs dist

要将必要的文档构建依赖项安装到您的开发环境中，请运行.pip install -r doc_requirements.txt

上传到 PyPI

上传所需的唯一应用程序是

• 麻线（点）。

您还需要一个 PyPI 令牌，最好将其保存在钥匙圈上。请参阅麻线钥匙圈 文档了解如何执行此操作。

生成作者/公关列表

您将需要一个个人访问令牌 https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/ 以便脚本可以访问 github NumPy 存储库。

• gitpython (点子)

• pygithub（点子）

发布了什么

• Wheels 我们目前支持 Windows、OSX 和 Linux 上的 Python 3.8-3.10。

  • Windows：使用 Github 操作构建的 32 位和 64 位轮子；

  • OSX：使用 Github actions 构建的 x64_86 和 arm64 OSX 轮子；

  • Linux：使用 Github 操作构建的 x64_86 和 aarch64 Manylinux2014 轮子。

• 其他 发行说明和变更日志

• 源代码分发 我们以 .tar.gz 格式构建源代码版本。

发布流程

就发布时间表达成一致

典型的发布时间表是一个测试版、两个候选版本和一个最终版本。最好先在邮件列表上讨论时间安排，以便人们能够按时提交、合并 doc wiki 编辑等。设置日期后，创建一个新的维护/xyz 分支，添加新的空版本主分支中下一个版本的注释并更新 Trac 里程碑。

确保当前分支正确构建包

当 PR 标头以 开头时，CI 就会造轮子REL。发布前的最后一个 PR 应该如此标记，并且所有测试都应该通过。您还可以这样做：

git clean -fxdq
python setup.py bdist_wheel
python setup.py sdist

有关构建过程本身的详细信息，最好阅读下面的分步说明。

笔记

对于测试版、候选版本和最终版本重复以下步骤。

检查弃用

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

检查C API版本号

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

• numpy/core/setup_common.py

• numpy/core/code_generators/cversions.txt

• numpy/core/include/numpy/numpyconfig.h

该过程分为三个步骤。

1. 如果 API 已更改，请增加 setup_common.py 中的 C_API_VERSION。仅当针对当前 API 编译的任何代码将向后兼容最新发布的 NumPy 版本时，API 才会保持不变。对 C 结构的任何更改或对公共接口的添加都会使新 API 不向后兼容。

2. 如果第一步中的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 不匹配”。

3. numpy/core/include/numpy/numpyconfig.h 将需要一个新的 NPY_X_Y_API_VERSION 宏，其中 X 和 Y 是发行版的主要版本号和次要版本号。如果包含文件中的某些函数或宏已被弃用，则仅需要从以前的版本增加为该宏指定的值。

numpy/core/setup_common.py 中的 C ABI 版本号只应针对主要版本进行更新。

检查发行说明

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

towncrier build –version“<版本>”git commit -m“创建发行说明”

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

使用“亮点”部分更新发行说明。提及以下一些内容：

• 主要新功能

• 已弃用和删除的功能

• 支持的Python版本

• 对于 SciPy，支持的 NumPy 版本

• 近期展望

分步说明

这是 Linux 上 NumPy 1.21.0 版本的演练，经过修改以使用 GitHub Actions 和 cibuildwheels 进行构建，并上传到 NumPy 的 anaconda.org 临时存储库。可以将命令复制到命令行中，但请务必将 1.21.0 替换为正确的版本。这应该与一般发布指南一起阅读 。

设施准备

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

• 可以将 Git 设置为使用密钥环来存储您的 GitHub 个人访问令牌。网上搜索一下详细信息。

• 您可以使用该keyring应用程序来存储 twine 的 PyPI 密码。有关详细信息，请参阅在线缠绕文档。

发布准备

添加/删除 Python 版本

添加或删除Python版本时，需要编辑三个文件：

• .github/workflows/wheels.yml # 用于 github cibuildwheel

• .travis.yml # 用于 cibuildwheel aarch64 构建

• setup.py # 用于分类器和最低版本检查。

如有必要，请在针对主端口和反向移植的普通 PR 中进行这些更改。使用BLD:前缀（构建标签）作为提交摘要将导致轮子构建运行，以便测试更改。目前，一旦 Manylinux 和 cibuildwheel 支持，我们就会在第一个 Python rc 之后发布新 Python 版本的轮子。对于 Python 3.11，我们能够在 rc1 发布后一周内发布。

向后移植拉请求

已标记为此版本的更改必须向后移植到maintenance/1.21.x 分支。

更新发布文档

在发布之前通常需要更新或创建四个文档：

• 变更日志

• 发行说明

• 文件.mailmap​

• 文件doc/source/release.rst​

这些更改应作为针对维护分支的普通 PR 进行。发布后，除了doc/source/release.rst 需要转发到主分支之外的所有文件。

生成变更日志

变更日志是使用变更日志工具生成的：

$ python tools/changelog.py $GITHUB v1.20.0..maintenance/1.21.x > doc/changelog/1.21.0-changelog.rst

其中GITHUB包含您的 GitHub 访问令牌。需要检查文本中是否有非标准贡献者名称，并删除依赖机器人条目。删除 PR 标题中可能存在的任何链接也是一个好主意，因为它们不能很好地转换为 Markdown，用等宽文本替换它们。非标准贡献者名称应通过更新文件来修复.mailmap ，这是一项艰巨的工作。最好在达到这一点之前进行几次试运行，并使用 GitHub 问题 ping 不法分子以获取所需的信息。

完成发行说明

如果这是生成发行说明的系列中的第一个版本，请参阅 中的发行说明doc/release/upcoming_changes/README.rst以了解如何执行此操作。生成发行说明还将删除doc/release/upcoming_changes/.

生成的发行说明总是需要一些修复，需要编写介绍，并且应该指出重大更改。对于补丁版本，还可以附加更改日志文本，但对于初始版本则不然，因为它太长了。查看以前的发行说明以了解这是如何完成的。请注意，:orphan:顶部的标记（如果存在）将需要更改，并且 索引文件将需要更新。.. currentmodule:: numpydoc/source/release.rst

检查pavement.py文件

检查 pavement.py 文件是否指向正确的发行说明。它应该在上次版本之后更新，但如果没有，请立即修复：

$ gvim pavement.py

发布演练

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

1. 准备发布提交

检查版本的分支，确保它是最新的，并清理存储库：

$ git checkout maintenance/1.21.x
$ git pull upstream maintenance/1.21.x
$ git submodule update
$ git clean -xdfq

完整性检查：

$ python3 -m spin test -m full

标记发布并推送标签。这需要 numpy 存储库的写权限：

$ git tag -a -s v1.21.0 -m"NumPy 1.21.0 release"
$ git push upstream v1.21.0

如果由于错误需要删除标签：

$ git tag -d v1.21.0
$ git push --delete upstream v1.21.0

2.造轮子

通过 cibuildwheel 构建轮子（首选）

在此过程开始时标记构建将通过 cibuildwheel 触发wheel构建，并将wheels和sdist上传到登台存储库。在 github 操作上运行的 CI（对于所有基于 x86 和 macOS arm64 的轮子）大约需要 1 1/4 小时。在 travis（对于 aarch64）上运行 CI 需要更少的时间。您可以在临时存储库中检查上传的文件，但请注意，它与您看到的正在运行的作业并不紧密同步。

如果您希望手动触发轮子构建，您可以这样做：

• 在 github actions -> Wheel builder上有一个“运行工作流程”按钮，单击它并选择要构建的标签

• travis上有一个“更多选项”按钮，单击它并选择要构建的分支。似乎没有构建标签的选项。

如果wheel构建由于不相关的原因失败，您可以单独重新运行它：

• 在 github actions 上选择Wheel builder，单击包含要重新运行的构建的提交。左侧有一个轮子构建列表，选择您想要重新运行的轮子构建，然后在结果页面上点击逆时针箭头按钮。

• 在travis上选择失败的构建，这将带您进入该构建的 travis 作业。点击重新启动作业按钮。

请注意，如果您确实需要重新运行作业，则需要删除 anaconda staging 存储库中上传的文件（如果有） ，旧文件不会被覆盖。

3.下载轮子

当轮子全部成功构建和暂存后，使用以下tools/download-wheels.py脚本从 Anaconda 暂存目录下载它们：

$ cd ../numpy
$ mkdir -p release/installers
$ python3 tools/download-wheels.py 1.21.0

4. 生成自述文件

这需要在下载所有安装程序之后、更新路面文件以继续开发之前完成：

$ paver write_release

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

创建下一个版本的发行说明并编辑它们以设置版本。这些笔记只是一个骨架，内容很少：

$ cp doc/source/release/template.rst doc/source/release/1.21.1-notes.rst
$ gvim doc/source/release/1.21.1-notes.rst
$ git add doc/source/release/1.21.1-notes.rst

将新的发行说明添加到文档发行列表中并更新 RELEASE_NOTES以下变量pavement.py：

$ gvim doc/source/release.rst pavement.py

提交结果：

$ git commit -a -m"REL: prepare 1.21.x for further development"
$ git push upstream HEAD

6.上传到PyPI

使用 上传到 PyPI twine。twine最近 PyPI 更改后需要最新版本的，3.4.1此处使用的版本：

$ cd ../numpy
$ twine upload release/installers/*.whl
$ twine upload release/installers/numpy-1.21.0.tar.gz  # Upload last.

如果其中一个命令在中间中断，您可能需要有选择地上传剩余的文件，因为 PyPI 不允许同一文件上传两次。应最后上传源文件，以避免如果 pip 用户在此过程中访问文件，可能会出现同步问题，从而导致 pip 从源代码构建而不是下载二进制轮。 PyPI 只允许单源分发，这里我们选择 zip 存档。

7.上传文件到github

转到https://github.com/numpy/numpy/releases，应该有一个，单击它并点击该标签的编辑按钮。有两种添加文件的方法，使用可编辑文本窗口和二进制上传。首先编辑使用 pandoc 从第一个版本翻译的内容。需要修复的事情：更改日志中的 PR 行（如果包含）已包装并需要解开，链接应更改为等宽文本。然后将内容复制到剪贴板并将其粘贴到文本窗口中。可能需要多次尝试才能使其看起来正确。然后v1.21.0 tagrelease/README.md

• release/installers/numpy-1.21.0.tar.gz作为二进制文件上传。

• release/README.rst作为二进制文件上传。

• doc/changelog/1.21.0-changelog.rst作为二进制文件上传。

• 如果这是预发布，请检查预发布按钮。

• 点击底部的按钮。{Publish,Update} release

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

笔记

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

仅最终版本需要此步骤，预发行版和大多数补丁版本可以跳过此步骤。将存储库克隆到 并使用新文档更新它：make merge-docnumpy/docdoc/build/merge

$ git clean -xdfq
$ git co v1.21.0
$ pushd doc
$ make docenv && source docenv/bin/activate
$ make merge-doc
$ pushd build/merge

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

$ gvim index.html +/'insert here'

此外，更新 version-switcher json 文件以添加新版本并更新标记为(stable)的版本：

$ gvim _static/versions.json

否则，仅zip应使用新标签名称更新链接。由于我们不再生成pdf文件，因此删除文件行（pdf 如果存在）：

$ gvim index.html +/'tag v1.21'

您可以在浏览器中“测试运行”新文档以确保链接有效：

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

更新稳定链接并更新：

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

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

$ python3 update.py
$ git commit -a -m"Add documentation for v1.21.0"
$ git push
$ deactivate
$ popd
$ popd

9. 在 numpy.org 上宣布发布（跳过预发布）

这假设您已经分叉了https://github.com/numpy/numpy.org：

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

• 对于所有版本，请转到页面底部并添加一行链接。例如，查看前面的链接。

• 对于*.0周期内的发布，请在顶部添加一个新部分，其中包含新功能的简短描述，并将新闻链接指向它。

提交并推送：

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

转到您的 Github 分支并发出拉取请求。

10. 向邮件列表公告

该版本应在 numpy-discussion、scipy-devel、scipy-user 和 python-announce-list 邮件列表上公布。查看之前的公告了解基本模板。贡献者和 PR 列表与上面的发行说明中生成的相同。如果您交叉发布，请确保 python-announce-list 是密件抄送，以便回复不会发送到该列表。

11. 发布后任务（预发布则跳过）

检查主要和转发端口的文档更改：

$ git checkout -b post-1.21.0-release-update
$ git checkout maintenance/1.21.x doc/source/release/1.21.0-notes.rst
$ git checkout maintenance/1.21.x doc/changelog/1.21.0-changelog.rst
$ git checkout maintenance/1.21.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 1.21.0 release."
$ git push origin HEAD

前往 GitHub 并制作 PR。

12.更新最旧支持的numpy

如果此版本是第一个支持新 Python 版本的版本，或者第一个为新平台或 PyPy 版本提供轮子的版本，则应更新https://github.com/scipy/oldest-supported-numpy中的版本固定。可以提交包含更改的 PR setup.cfg，或者打开一个包含所需更改信息的问题。

分支演练

本指南包含在 Linux 上分支 NumPy 1.21.x 的演练。这些命令可以复制到命令行中，但请务必用正确的版本替换 1.21 和 1.22。最好.mailmap在创建分支之前尽可能保持最新状态，这可能需要几周的时间。

这应该与一般发布指南一起阅读 。

分支

建立分支

仅当启动新的维护分支时才需要这样做。由于 NumPy 现在依赖标签来确定版本，因此主分支中新开发周期的开始需要一个带注释的标签。其操作如下：

$ git checkout main
$ git pull upstream main
$ git commit --allow-empty -m'REL: Begin NumPy 1.22.0 development'
$ git push upstream HEAD

如果由于合并新 PR 导致推送失败，请执行以下操作：

$ git pull --rebase upstream

并重复推动。推送成功后，标记它：

$ git tag -a -s v1.22.0.dev0 -m'Begin NumPy 1.22.0 development'
$ git push upstream v1.22.0.dev0

然后创建新分支并推送它：

$ git branch maintenance/1.21.x HEAD^
$ git push upstream maintenance/1.21.x

为进一步开发准备主分支

创建一个 PR 分支，为 main 的进一步开发做准备：

$ git checkout -b 'prepare-main-for-1.22.0-development' v1.22.0.dev0

删除发行说明片段：

$ git rm doc/release/upcoming_changes/[0-9]*.*.rst

创建新的发行说明框架并添加到索引：

$ cp doc/source/release/template.rst doc/source/release/1.22.0-notes.rst
$ gvim doc/source/release/1.22.0-notes.rst  # put the correct version
$ git add doc/source/release/1.22.0-notes.rst
$ gvim doc/source/release.rst  # add new notes to notes index
$ git add doc/source/release.rst

更新pavement.py并更新RELEASE_NOTES变量以指向新的注释：

$ gvim pavement.py
$ git add pavement.py

更新cversions.txt以添加当前版本。在早期阶段不应该担心新的哈希值，只需按照之前的做法添加注释即可：

$ gvim numpy/core/code_generators/cversions.txt
$ git add numpy/core/code_generators/cversions.txt

检查您的工作，提交并推送：

$ git status  # check work
$ git commit -m'REL: Prepare main for NumPy 1.22.0 development'
$ git push origin HEAD

现在提出拉取请求。