发布版本#

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

如何准备发布版本#

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

当前构建和发布信息#

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

支持的平台和版本#

NEP 29 概述了支持的 Python 版本; 对于 2020 年上半年,这将是 Python >= 3.6.每次我们将代码合并到主分支时,都会针对所有这些版本测试 NumPy.二进制安装程序可能适用于这些版本的子集(请参见下文).

  • OS X

    支持 OS X 版本 >= 10.9,关于 Python 版本支持请参考 NEP 29 .我们为 OSX 构建了与 Python.org Python,系统 Python,homebrew 和 macports 兼容的二进制 wheel - 有关详细信息,请参见此 OSX wheel building summary .

  • Windows

    我们在 Windows 上构建 32 位和 64 位 wheel.支持 Windows 7,8 和 10.我们使用 mingw-w64 toolchain , cibuildwheels 和 GitHub actions 构建 NumPy.

  • Linux

    我们为 NumPy 构建并发布 manylinux_2_28 wheels.许多 Linux 发行版都包含它们自己的 NumPy 二进制版本.

  • BSD / Solaris

    不提供二进制文件,但据报告已在 Solaris 和 BSD 上成功构建.

工具链#

我们在云基础设施上构建所有 wheel - 因此此编译器列表仅用于信息和本地调试构建.请参阅 numpy wheels 仓库中的 .travis.yml 脚本,以获取使用 multibuild 的构建配方的过时来源.

编译器#

使用的 gcc 版本与 Python 本身在每个平台上构建时使用的版本相同.目前这意味着:

  • 目前 travis 上的 OS X 构建使用 clang .当针对 Python.org 安装程序中的 Python 进行构建时,从 travis-ci OSX 10.9 VM 安全地构建 OSX >= 10.6 的二进制 wheel 似乎是可行的;

  • Windows 构建使用 mingw-w64 toolchain ;

  • Manylinux2014 wheels 使用 Manylinux docker 镜像上提供的 gcc.

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

OpenBLAS#

所有 wheel 都链接到通过 openblas-libs 仓库提供的 OpenBLAS 版本.共享对象(或 DLL)与 wheel 一起提供,并重命名以防止与文件系统中可能存在的其他 OpenBLAS 共享对象发生名称冲突.

构建源存档和 wheels#

NumPy wheels 和 sdist 现在使用 cibuildwheel 和 github actions 构建.

构建文档#

我们不再构建 PDF 文件.所有需要的只是

  • virtualenv (pip).

其他要求将在文档构建过程中自动满足.

上传到 PyPI#

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

  • twine (pip).

您还需要一个 PyPI 令牌,最好将其保存在密钥环上.有关如何执行此操作,请参见 twine keyring 文档.

生成作者/PR 列表#

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

  • gitpython (pip)

  • pygithub (pip)

发布内容#

  • Wheels 我们目前在 Windows,OSX 和 Linux 上支持 Python 3.10-3.13.

    • Windows:使用 Github actions 构建的 32 位和 64 位 wheel;

    • OSX:使用 Github actions 构建的 x64_86 和 arm64 OSX wheels;

    • Linux:使用 Github actions 构建的 x64_86 和 aarch64 Manylinux2014 wheels.

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

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

发布流程#

确定发布计划#

典型的发布计划包括一个 beta 版本,两个候选发布版本和一个最终发布版本.最好先在邮件列表中讨论时间,以便人们能够及时提交他们的代码,合并文档 wiki 编辑等.确定日期后,创建一个新的 maintenance/x.y.z 分支,在主分支中为下一个版本添加新的空的发行说明,并更新 Trac Milestones.

确保当前分支可以正确构建软件包#

当 PR 标头以 REL 开头时,CI 构建 wheels.您在发布之前的最后一个 PR 应该这样标记,并且所有测试都应该通过.您也可以执行以下操作:

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

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

备注

以下步骤将针对 beta 版本,候选发布版本和最终发布版本重复执行.

检查弃用#

在 the release branch is made 之前,应检查所有应删除的已弃用代码是否已实际删除,并且所有新的弃用都应在文档字符串或弃用警告中说明代码将被删除的版本.

检查 C API 版本号#

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

  • numpy/_core/meson.build

  • numpy/_core/code_generators/cversions.txt

  • numpy/_core/include/numpy/numpyconfig.h

该过程包含三个步骤.

  1. 如果 API 已更改,请递增 numpy/core/meson.build 中的 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,则编译 release 不应给出警告“在构建开始时检测到 API 不匹配”.

  3. numpy/_core/include/numpy/numpyconfig.h 将需要一个新的 NPY_X_Y_API_VERSION 宏,其中 X 和 Y 是发行版的主要和次要版本号.如果 include 文件中的某些函数或宏已弃用,则只需将赋予该宏的值从先前版本增加即可.

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.1.0 版本的详细步骤,经过修改,可以使用 GitHub Actions 和 cibuildwheels 构建,并上传到 anaconda.org staging repository for NumPy .这些命令可以复制到命令行中,但请务必将 2.1.0 替换为正确的版本.本文应与 general release guide 一起阅读.

设施准备#

在开始发布之前,请使用 requirements/_requirements.txt 文件来确保您拥有所需的软件.大多数软件可以使用 pip 安装,但有些软件需要 apt-get,dnf 或您的系统用于软件的其他工具.您还需要一个 GitHub 个人访问令牌 (PAT) 来推送文档.以下是一些简化操作的方法:

  • 可以设置 Git 使用密钥环来存储您的 GitHub 个人访问令牌.在线搜索了解详情.

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

发布前#

添加/删除 Python 版本#

在添加或删除 Python 版本时,需要编辑以下三个文件:

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

  • tools/ci/cirrus_wheels.yml # 用于 cibuildwheel aarch64/arm64 构建

  • pyproject.toml # 用于分类器和最低版本检查.

在针对 main 的普通 PR 中进行这些更改,并在必要时进行反向移植.在提交摘要的标题行末尾添加 [wheel build] ,以便运行 wheel 构建来测试更改.我们目前在第一个 Python rc 发布后,一旦 manylinux 和 cibuildwheel 支持它,就会发布新 Python 版本的 wheels.对于 Python 3.11,我们能够在 rc1 发布后一周内发布.

反向移植拉取请求#

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

更新 2.1.0 里程碑#

查看带有 2.1.0 里程碑的问题/prs,要么将它们推迟到以后的版本,要么删除里程碑.您可能需要添加里程碑.

创建发布 PR#

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

  • 变更日志

  • 发行说明

  • .mailmap 文件

  • pyproject.toml 文件

这些更改应该在针对维护分支的普通 PR 中进行.提交标题应包含 [wheel build] 指令,以测试 wheel 是否构建.其他小的,杂项修复可能属于此 PR 的一部分.提交消息可能如下所示:

REL: Prepare for the NumPy 2.1.0 release [wheel build]

- Create 2.1.0-changelog.rst.
- Update 2.1.0-notes.rst.
- Update .mailmap.
- Update pyproject.toml

设置发布版本#

检查 pyproject.toml 文件,并在需要时设置发布版本:

$ gvim pyproject.toml

检查 pavement.py 和 doc/source/release.rst 文件#

检查 pavement.py 文件是否指向正确的发行说明.它应该在上次发布后已经更新,但如果没有,请立即修复.还要确保 notes 在 release.rst 文件中有一个条目:

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

生成变更日志#

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

$ spin changelog $GITHUB v2.0.0..maintenance/2.1.x > doc/changelog/2.1.0-changelog.rst

其中 GITHUB 包含您的 GitHub 访问令牌.需要检查文本中是否存在非标准贡献者姓名,并删除 dependabot 条目.最好也删除 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.1.0-notes.rst

一旦 notes-towncrier 的内容被合并到发行说明中, .. include:: notes-towncrier.rst 指令就可以被移除.这些说明总是需要一些修复,介绍需要被编写,并且重要的更改应该被指出.对于补丁版本,也可以附加变更日志文本,但对于初始版本则不附加,因为它太长.查看以前的发行说明以了解如何完成此操作.

发布演练#

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

1. 准备发布提交#

检出发行的分支,确保它是最新的,并清理存储库:

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

健全性检查:

$ python3 -m spin test -m full

标记发布并推送标签.这需要对 numpy 存储库的写入权限:

$ git tag -a -s v2.1.0 -m"NumPy 2.1.0 release"
$ git push upstream v2.1.0

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

$ git tag -d v2.1.0
$ git push --delete upstream v2.1.0

2. 构建 wheel 包#

在此过程开始时标记构建将通过 cibuildwheel 触发 wheel 包的构建,并将 wheel 包和 sdist 上传到暂存仓库.在 github actions 上的 CI 运行(适用于所有基于 x86 的和 macOS arm64 wheel 包)大约需要 1 1/4 小时.在 cirrus 上的 CI 运行(适用于 aarch64 和 M1)花费的时间更少.您可以在 staging repository 中检查已上传的文件,但请注意,它与您看到的运行作业的同步并不紧密.

如果您希望手动触发 wheel 构建,可以这样做:

  • 在 github actions -> Wheel builder 上,有一个“Run workflow”按钮,单击它并选择要构建的标签.

  • 在 Cirrus 上,我们目前没有一种简单的方法来手动触发构建和上传.

如果 wheel 构建由于无关的原因而失败,您可以单独重新运行它:

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

  • 在 cirrus 上,登录 cirrusci,查找 v2.1.0 标签并重新运行失败的作业.

3. 下载wheel包#

当所有 wheel 包都已成功构建并暂存后,使用 tools/download-wheels.py 脚本从 Anaconda 暂存目录下载它们:

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

4. 生成 README 文件#

这需要在下载所有安装程序之后,但在更新 pavement 文件以进行持续开发之前完成:

$ paver write_release

5. 上传到 PyPI#

使用 twine 上传到 PyPI.在最近的 PyPI 更改之后,需要一个最近版本的 twine ,这里使用了版本 3.4.1

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

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

6. 上传文件到 GitHub#

前往 numpy/numpy ,应该会有一个 v2.1.0 tag ,点击它,然后点击该标签的编辑按钮,并将标题更新为“v2.1.0 (<日期>)”.有两种添加文件的方式,使用可编辑的文本窗口和作为二进制上传.首先编辑使用 pandoc 从 rst 版本翻译过来的 release/README.md .需要修复的内容:如果包含在内,则来自变更日志的 PR 行会被包装,需要解包,链接应该更改为等宽文本.然后将内容复制到剪贴板并将其粘贴到文本窗口中.可能需要多次尝试才能使其看起来正确.然后

  • 以二进制文件上传 release/installers/numpy-2.1.0.tar.gz .

  • 以二进制文件上传 release/README.rst .

  • 以二进制文件上传 doc/changelog/2.1.0-changelog.rst .

  • 如果这是预发布版本,请检查预发布按钮.

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

7. 上传文档到 numpy.org (预发布版本跳过)#

备注

您需要一个 GitHub 个人访问令牌才能推送更新.

此步骤仅在最终版本中需要,预发布版本和大多数补丁版本可以跳过. make merge-doc 将 numpy/doc 仓库克隆到 doc/build/merge 中,并使用新文档更新它:

$ git clean -xdfq
$ git co v2.1.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 首页的“insert here”注释之后添加一个新部分:

$ gvim index.html +/'insert here'

此外,更新 version-switcher json 文件以添加新版本,并更新标记为 (stable) 和 preferred 的版本:

$ gvim _static/versions.json

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

$ python3 update.py

您可以在浏览器中“测试运行”新文档,以确保链接有效,但版本下拉列表不会更改,它从 numpy.org 获取信息:

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

更新 stable 链接并更新:

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

一切看起来令人满意后,更新,提交并上传更改:

$ git commit -a -m"Add documentation for v2.1.0"
$ git push git@github.com:numpy/doc
$ popd

8. 将维护分支重置为开发状态(预发布版跳过)#

创建下一个版本的发行说明,并对其进行编辑以设置版本.这些说明将是一个框架,内容很少:

$ git checkout -b begin-2.1.1 maintenance/2.1.x
$ cp doc/source/release/template.rst doc/source/release/2.1.1-notes.rst
$ gvim doc/source/release/2.1.1-notes.rst
$ git add doc/source/release/2.1.1-notes.rst

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

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

更新 pyproject.toml 中的 version

$ gvim pyproject.toml

提交结果:

$ git commit -a -m"MAINT: Prepare 2.1.x for further development"
$ git push origin HEAD

前往 GitHub 并创建一个 PR.它应该很快被合并.

9. 在 numpy.org 上宣布发布(预发布版本跳过)#

这假设您已经 fork 了 numpy/numpy.org

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

  • 对于所有版本,转到页面底部并添加一行链接.查看之前的链接作为示例.

  • 对于一个周期中的 *.0 版本,在顶部添加一个新部分,其中简要描述新功能,并将新闻链接指向它.

提交并推送:

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

前往 GitHub 并创建一个 PR.

10. 向邮件列表发布公告#

应该在 numpy-discussion,scipy-devel 和 python-announce-list 邮件列表上发布该版本. 查看以前的公告以获取基本模板.贡献者和 PR 列表与上面为发行说明生成的列表相同.如果您交叉发布,请确保 python-announce-list 是 BCC,这样回复将不会发送到该列表.

11. 发布后更新 main 分支(预发布版本跳过)#

检出 main 并向前移植文档更改.如果程序发生更改或改进,您可能还需要更新这些说明:

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

前往 GitHub 并创建一个 PR.

分支演练#

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

这应该与 general release guide 一起阅读.

分支#

创建分支#

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

$ 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

准备 main 分支以进行进一步开发#

创建一个 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

现在发出一个 pull request.