此文件概述了为numpy生成二进制版本所需的内容。
目前关于构建和发布NumPy和SciPy的信息分散在几个地方。应该在一个地方进行总结、更新,并在必要时进行更详细的描述。下面的部分列出了可以找到有用信息的所有地方。
INSTALL.rst.txt
release.sh
pavement.py
https://github.com/numpy/numpy/blob/master/doc/HOWTO_RELEASE.rst.txt
https://www.scipy.org/Installing_SciPy and links on that page.
https://github.com/numpy/numpy-vendor
NEP 29 概述支持哪些Python版本;对于2020年上半年,这将是Python>=3.6。每次我们将代码合并到master时,我们都会针对所有这些版本测试NumPy。二进制安装程序可以用于这些版本的一个子集(见下文)。
支持OS X版本>=10.9,有关Python版本支持,请参阅 NEP 29 . 我们为OSX构建了与Python.org网站Python、系统Python、自制软件和macports—看到这个了吗 OSX wheel building summary 有关详细信息。
我们在Windows上构建32位和64位控制盘。支持Windows 7、8和10。我们使用 mingw-w64 toolchain 在测量仪上。
我们建造和运输 manylinux1 NumPy的轮子。许多Linux发行版都包含自己的二进制版本NumPy。
没有提供二进制文件,但已报告在Solaris和BSD上成功生成。
我们在云基础设施上构建我们所有的轮子——所以这个编译器列表是为了本地的信息和调试构建。见 .travis.yml 和 appveyor.yml 中的脚本 numpy wheels 对建立配方的确定来源的报告。注意使用PIP提供的包。
.travis.yml
appveyor.yml
使用相同的gcc版本作为在每个平台上构建python本身的版本。目前这意味着:
OS X建立在Travis当前使用的基础上 clang . 当使用python.org安装程序针对python进行构建时,似乎可以从travis ci osx 10.9 vms安全地构建osx>=10.6的二进制车轮;
Windows生成使用 mingw-w64 toolchain ;
manylinux1轮子使用manylinux docker图像上提供的gcc。
你需要赛通来构建双星。赛通编纂 .pyx NumPy发行版中的文件 .c 文件夹。
.pyx
.c
所有控制盘都链接到 OpenBLAS 通过 openblas-libs 回购。共享对象(或DLL)附带在控制盘中,重命名以防止与文件系统中可能存在的其他OpenBLAS共享对象发生名称冲突。
您将需要对numpy车轮的写入权限才能触发车轮生成。
Python(s) python.org 或者linux发行版。
赛顿(pip)
虚拟环境(PIP)
摊铺机(PIP)
潘多克 pandoc.org 或者linux发行版。
numpy-wheels https://github.com/MacPython/numpy-wheels (克隆)
构建文档需要大量的 Latex .sty 文件夹。全部安装以避免加重。
.sty
Sphinx(pip)
NUMPYDOC(PIP)
Matplotlib
TexLive(或Windows上的MikTex)
惊艳 https://github.com/MacPython/terryfy (克隆)。
美丽的灵魂4(pip)
离域(PIP)
审计轮(PIP)
缠绕(PIP)
你需要个人通行证 https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/ 以便脚本可以访问github NumPy存储库。
吉比特(PIP)
毕赤(PIP)
virtualenv是一个非常有用的工具,它可以保存多个版本的软件包。在铺路机脚本中也使用它来构建文档。
我们目前在Windows、OSX和Linux上支持python3.6-3.8
窗口:32位和64位轮子使用Appveyor构建;
OSX:x64×86 OSX车轮采用travis ci制造;
Linux:使用travis ci构建的32位和64位Manylinux1控制盘。
见 numpy wheels 正在生成存储库以了解更多详细信息。
发行说明
Changelog
我们以.zip和.tar.gz格式构建源版本。
典型的发布时间表是一个测试版、两个候选版本和一个最终版本。最好先讨论邮件列表上的时间安排,以便人们按时提交提交,合并文档wiki编辑等。设置日期后,创建一个新的Maintenance/x.y.z分支,在主分支中为下一个版本添加新的空发行说明,并更新Trac里程碑。
git clean -fxd python setup.py bdist python setup.py sdist
要在一切设置正确后实际构建二进制文件发布.sh可以使用脚本。对于构建过程本身的细节,最好阅读路面.py脚本。
注解
对于测试版、发布候选版本和最终版本,重复以下步骤。
在创建发布分支之前,应该检查应该删除的所有不推荐的代码是否都已实际删除,并且所有新的不推荐都在docstring或不推荐警告中指明要删除代码的版本。
C API版本需要在三个地方进行跟踪
numpy/core/setup_common.py
numpy/core/code_generators/cversions.txt
numpy/core/include/numpy/numpyconfig.h
这个过程有三个步骤。
如果API已更改,请在setup_common.py中增加C_api_版本。只有当针对当前API编译的任何代码与上次发布的numpy版本向后兼容时,API才保持不变。对C结构的任何更改或对公共接口的任何添加都将使新的API不向后兼容。
如果第一步中的Cu APIu版本已更改,或者如果API的哈希已更改,则cversions.txt文件文件需要更新。要检查散列,请运行脚本numpy/core/版本.py并注意打印的API散列。如果该哈希与numpy/core/codeu生成器中的最后一个哈希不匹配/cversions.txt文件哈希值已更改。使用适当的Cu APIu版本和散列,将新条目添加到cversions.txt文件. 如果API版本没有更改,但哈希不同,则需要注释掉该API版本的上一个条目。例如,在numpy1.9中添加了注释,这改变了哈希,但是API与1.8中的相同。散列用于检查API更改,但它不是确定的。
如果步骤1和2正确完成,编译发行版时不应发出警告“在构建开始时检测API不匹配”。
numpy/core/include/numpy/numpyconfig.h需要一个新的npy-x-y-api-version宏,其中x和y是版本的主版本号和次版本号。如果不推荐使用include文件中的某些函数或宏,则只需从以前的版本增加为该宏给定的值。
numpy/core/setup_common.py中的c abi版本号只应针对主要版本进行更新。
使用 towncrier 构建发行说明并提交更改。所有的碎片都会被移除 doc/release/upcoming_changes 并添加 doc/release/<version>-note.rst . 由于TownMaster(19.0)的最后一个版本当前已过时,请注意。
doc/release/upcoming_changes
doc/release/<version>-note.rst
towncrier--version“<version>”git commit-m“创建发行说明”
检查发行说明是否是最新的。
使用突出部分更新发行说明。请注意以下几点:
主要新功能 已弃用和删除的功能 支持的python版本 对于scipy,支持numpy版本 近期展望
主要新功能
已弃用和删除的功能
支持的python版本
对于scipy,支持numpy版本
近期展望
标识发布的提交哈希,例如1B2E1d63ff。
Git Co 1B2E1d63FF发出关于分离头的警告
首先,更改/检查以下变量 pavement.py 取决于发布版本:
RELEASE_NOTES = 'doc/release/1.7.0-notes.rst' LOG_START = 'v1.6.0' LOG_END = 'maintenance/1.7.x'
做任何其他更改。准备释放时,请执行以下更改:
diff --git a/setup.py b/setup.py index b1f53e3..8b36dbe 100755 --- a/setup.py +++ b/setup.py @@ -57,7 +57,7 @@ PLATFORMS = ["Windows", "Linux", "Solaris", "Mac OS- MAJOR = 1 MINOR = 7 MICRO = 0 -ISRELEASED = False +ISRELEASED = True VERSION = '%d.%d.%drc1' % (MAJOR, MINOR, MICRO) # Return the git revision as a string
并确保 VERSION 变量设置正确。
VERSION
现在您可以让发布提交和标记。我们建议您不要立即推送提交或标记,以防需要执行更多清理。我们倾向于推迟标签的推送,直到我们确信这是已发布代码的确切形式(请参阅: 推送发布标签并提交 ):
git commit-s-m“rel:release.”setup.py git tag-s<version>
这个 -s 标记生成一个PGP(通常是GPG)签名标记。请在释放标签上签名。
-s
发布标签应该在注释(标签消息)中有发布号。不幸的是,标记的名称可以在不破坏签名的情况下更改,而消息的内容不能更改。
请参见:https://github.com/scipy/scipy/issues/4919讨论签署发布标签,以及https://keyring.debian.org/creating-key.html有关创建GPG密钥(如果没有)的说明。
要使您的密钥更易于识别,请考虑将您的密钥发送给公共密钥服务器,命令如下:
gpg --send-keys <yourkeyid>
在setup.py中增加版本号。发布候选文件应在x.y.z格式后附加“rc1”(或“rc2”,“rcn”)。
还可以在cversions.txt中创建一个新版本的哈希,并在numpyconfig.h中定义相应的版本npy_x_y_API_version。
见 MacPython/numpy wheels 储存库。
在该存储库中编辑文件:
azure/posix.yml
azure/windows.yml .
azure/windows.yml
在这两种情况下,设置 BUILD_COMMIT 当前发布标签的变量-例如 v1.19.0 ::
BUILD_COMMIT
v1.19.0
$ gvim azure/posix.yml azure/windows.yml $ git commit -a $ git push upstream HEAD
确保已按下释放标签。
通过将编辑提交到存储库来触发生成。请注意,可以在分支上执行此操作,但必须将其推到 MacPython/numpy-wheels 存储库触发上载,因为只有该repo具有允许上载的适当令牌。
MacPython/numpy-wheels
轮子一旦建成,就会出现在https://anaconda.org/multibuild-wheels-staging/numpy
生成要上载的变更日志和注释,方法为:
paver write_release
DO:
cd doc/ make dist
检查文档是否处于可构建状态。然后,在标记之后,在numpy/doc repo中创建文档的存档:
# This checks out github.com/numpy/doc and adds (``git add``) the # documentation to the checked out repo. make merge-doc # Now edit the ``index.html`` file in the repo to reflect the new content. # If the documentation is for a non-patch release (e.g. 1.19 -> 1.20), # make sure to update the ``stable`` symlink to point to the new directory. ln -sfn <latest_stable_directory> stable # Commit the changes git -C build/merge commit -am "Add documentation for <version>" # Push to numpy/doc repo git -C build/merge push
轮子和源文件应该上传到pypi。
您应该先上传控制盘,然后上传源代码格式,以确保PIP用户在期望使用二进制控制盘时不会意外地安装源代码。
您可以使用 wheel-uploader 脚本来自https://github.com/macpython/terryfy。下面是下载所有窗口、manylinux、osx轮子和上传到pypi的推荐咒语。::
wheel-uploader
NPY_WHLS=~/wheelhouse # local directory to cache wheel downloads CDN_URL=https://anaconda.org/multibuild-wheels-staging/numpy/files wheel-uploader -u $CDN_URL -w $NPY_WHLS -v -s -t win numpy 1.11.1rc1 wheel-uploader -u $CDN_URL -w warehouse -v -s -t macosx numpy 1.11.1rc1 wheel-uploader -u $CDN_URL -w warehouse -v -s -t manylinux1 numpy 1.11.1rc1
这个 -v 标志给出详细反馈, -s 使脚本在上载之前使用GPG密钥对轮子进行签名。别忘了在源tarball之前上传轮子,所以没有时间让人们从预期的二进制安装切换到从pypi安装的源安装。
-v
有两种方法可以更新pypi上的源版本,第一种方法是:
$ git clean -fxd # to be safe $ python setup.py sdist --formats=gztar,zip # to check # python setup.py sdist --formats=gztar,zip upload --sign
这将要求您输入密钥PGP密码,以便对构建的源包进行签名。
第二种方法是在pypi的Web界面中,在sdist目录中上载pkg_信息文件。源tarball也可以通过这个界面上传。
最后,现在您确信这个标记正确地定义了您发布的源代码,您可以将标记推送并将发布提交到GitHub::
git push # Push release commit git push upstream <version> # Push tag named <version>
在哪里? upstream 指向主https://github.com/numpy/numpy.git存储库。
upstream
带有下载站点链接的发布公告应该放在scipy.org首页的侧边栏中。
scipy.org应该是位于https://github.com/scipy/scipy.org的公关。需要修改的文件是 www/index.rst . 寻找 News .
www/index.rst
News
如果此版本是第一个支持新Python版本的版本,或者是第一个为新平台或PyPy版本提供控制盘的版本,那么https://github.com/scipy/oldest-supported-numpy应该更新。或者提交一份带有更改的请购单 setup.cfg 在那里,或者打开一个问题,提供所需更改的信息。
setup.cfg
pyythy或python的发布列表也应该公布。
在beta/RC阶段,应该在邮件列表中发布一个显式的请求,请求使用其他几个库(SciPy/Matplotlib/Pygame)测试二进制文件。
给LWN的编辑发电子邮件,让他们知道这个版本。网址:https://lwn.net/op/faq.lwn contact
在发布最终版本之后,还有一些管理任务需要完成:
将发布分支中的端口更改转发到发行说明,并将发布脚本(如果有的话)转发到主分支。 更新TRAC中的里程碑。
将发布分支中的端口更改转发到发行说明,并将发布脚本(如果有的话)转发到主分支。
更新TRAC中的里程碑。
此文件包含Linux上Numpy1.19.0版本的演练,针对在azure上构建和上载到进行了修改anaconda.org这些命令可以复制到命令行中,但一定要用正确的版本替换1.19.0。
这应与中的一般说明一起阅读 releasing .
为此版本标记的更改必须向后移植到maintenance/1.19.x分支。
文件 doc/changelog/1.19.0-changelog.rst 应更新以反映变更和贡献者的最终列表。此文本可以通过以下方式生成:
doc/changelog/1.19.0-changelog.rst
$ python tools/changelog.py $GITHUB v1.18.0..maintenance/1.19.x > doc/changelog/1.19.0-changelog.rst
在哪里? GITHUB 包含您的Github访问令牌。此文本也可以附加到 doc/release/1.19.0-notes.rst 适用于补丁发布,但不适用于像 1.19.0 ,作为的更改日志 *.0 释放时间往往过长。这个 doc/source/release.rst 文件还应更新为指向新发行说明的链接。这些更改应提交给维护分支,稍后将转发给主控。应该检查变更日志中的名称重复或短名称以及 .mailmap 如果需要,更新文件。
GITHUB
doc/release/1.19.0-notes.rst
1.19.0
*.0
doc/source/release.rst
.mailmap
填写发行说明 doc/release/1.19.0-notes.rst 引起重大变化。
注意,在下面的代码片段中, upstream 指的是Github上的根存储库和 origin 在你的个人账户里。如果没有复刻存储库,而只是在本地克隆它,则可能需要进行调整。您也可以编辑 .git/config 并添加 upstream 如果它还没有出现。
origin
.git/config
签出该版本的分支,确保它是最新的,并清理存储库:
$ git checkout maintenance/1.19.x $ git pull upstream maintenance/1.19.x $ git submodule update $ git clean -xdfq
编辑pavement.py和setup.py,如howto_版本中所述:
$ gvim pavement.py setup.py # Generally only setup.py needs updating $ git commit -a -m"REL: NumPy 1.19.0 release."
清醒检查:
$ python3 runtests.py -m "full"
将此版本直接推到维护分支的末端。这需要对numpy存储库的写入权限::
$ git push upstream HEAD
摊铺机用于构建源发布。它将创建 release 和 release/installers 目录和放置 *.zip 和 *.tar.gz 后者中的源代码发布。::
release
release/installers
*.zip
*.tar.gz
$ python3 -m cython --version # check for correct cython version $ paver sdist # sdist will do a git clean -xdfq, so we omit that
通过将numpy wheels存储库指向此提交来触发轮子构建。这可能需要一个小时。numpy wheels存储库是从 https://github.com/MacPython/numpy-wheels . 如果这是一个系列中的第一个版本,那么从pull开始,因为repo可能已被其他人访问和更改,然后为该系列创建一个新分支。如果分支已存在,请跳过以下步骤:
$ cd ../numpy-wheels $ git co master $ git pull upstream master $ git branch v1.19.x
签出新分支并编辑 azure-pipelines.yml 和 .travis.yml 文件以确保它们具有正确的版本,并将 REL 上面为创建的提交 BUILD_COMMIT . 这个 azure/posix.yml 和 .travis.yml 文件可能还需要更新Cython版本以跟上Python发行版,但通常只需要这样做:
azure-pipelines.yml
REL
$ git checkout v1.19.x $ gvim azure-pipelines .travis.yml $ git commit -a -m"NumPy 1.19.0 release." $ git push upstream HEAD
现在等等。如果您对所花费的时间感到紧张--构建可能需要一段时间--您可以通过以下链接检查构建进度 https://github.com/MacPython/numpy-wheels 检查生成状态。在继续之前,请检查是否已构建所有需要的控制盘并将其上载到临时存储库。
请注意,有时构建(如测试)由于不相关的原因而失败,您需要重新运行它们。您需要在“numpy”下登录才能在azure上执行此操作。
当轮子都已成功地建立和暂存,下载他们从Anaconda暂存目录使用 tools/download-wheels.py 脚本::
tools/download-wheels.py
$ cd ../numpy $ python3 tools/download-wheels.py 1.19.0
这需要在下载所有安装程序之后,但在更新铺装层文件以继续开发之前完成:
$ paver write_release
一旦车轮已经建立和下载没有错误的标签 REL 提交,使用gpg密钥签名:
$ git tag -s -m"NumPy 1.19.0 release" v1.19.0
您应该将您的公共GPG密钥上传到GitHub,这样标签将在那里显示为“已验证”。
检查中的文件 release/installers 有正确的版本,然后将标签推到上游:
$ git push upstream v1.19.0
我们等到这一点再推标签,因为它是公共的,推后不应该再更改。
添加另一个 REL 提交到numpy维护分支,它重置 ISREALEASED 旗到 False 并递增版本计数器:
ISREALEASED
False
$ gvim pavement.py setup.py
为下一个版本创建发行说明并编辑它们以设置版本:
$ cp doc/source/release/template.rst doc/source/release/1.19.1-notes.rst $ gvim doc/source/release/1.19.1-notes.rst $ git add doc/source/release/1.19.1-notes.rst
向文档发布列表中添加新的发布说明:
$ gvim doc/source/release.rst
提交结果:
$ git commit -a -m"REL: prepare 1.19.x for further development" $ git push upstream HEAD
上传到pypi使用 twine . 最新版本的 twine 在最近的pypi更改后需要,版本 3.1.1 这里用的是:
twine
3.1.1
$ cd ../numpy $ twine upload release/installers/*.whl $ twine upload release/installers/numpy-1.19.0.zip # Upload last.
如果其中一个命令中途中断,您可能需要有选择地上载其余的文件,因为PyPI不允许同一个文件上载两次。源文件应最后上载,以避免在进程中pip用户访问文件时可能出现的同步问题。注意,PyPI只允许一个源代码分发,这里我们选择了zip存档。
去 https://github.com/numpy/numpy/releases ,应该有一个 v1.19.0 tag ,单击它并单击该标记的“编辑”按钮。有两种添加文件的方法,使用可编辑文本窗口和二进制上传。剪切并粘贴 release/README.md 将文件内容放入文本窗口。您可能需要进行一些编辑以使其看起来正确。那么
v1.19.0 tag
release/README.md
上传 release/installers/numpy-1.19.0.tar.gz 作为二进制文件。
release/installers/numpy-1.19.0.tar.gz
上传 release/installers/numpy-1.19.0.zip 作为二进制文件。
release/installers/numpy-1.19.0.zip
上传 release/README.rst 作为二进制文件。
release/README.rst
上传 doc/changelog/1.19.0-changelog.rst 作为二进制文件。
如果是预发布,请检查预发布按钮。
击中 {{Publish,Update}} release 按钮在底部。
{{Publish,Update}} release
此步骤仅适用于最终版本,对于预版本可以跳过。 make merge-doc 克隆 numpy/doc 回购成 doc/build/merge 并用新文档更新:
make merge-doc
numpy/doc
doc/build/merge
$ pushd doc $ make dist $ make merge-doc $ popd
如果发布系列是新的,则需要向 doc/build/merge/index.html 在“插入此处”评论之后的首页:
doc/build/merge/index.html
$ gvim doc/build/merge/index.html +/'insert here'
否则,只有 zip 和 pdf 应使用新标记名更新链接:
zip
pdf
$ gvim doc/build/merge/index.html +/'tag v1.19'
您可以在浏览器中“测试运行”新文档,以确保链接正常工作:
$ firefox doc/build/merge/index.html
一旦一切都令人满意,提交并上传更改:
$ pushd doc/build/merge $ git commit -am"Add documentation for v1.19.0" $ git push $ popd
这假设你已经复刻了 https://github.com/scipy/scipy.org ::
$ cd ../scipy.org $ git checkout master $ git pull upstream master $ git checkout -b numpy-1.19.0 $ gvim www/index.rst # edit the News section $ git commit -a $ git push origin HEAD
现在去你的叉子那里,为树枝做一个拉动请求。
发布应该在numpy讨论、scipy-devel、scipy-user和python-announce list邮件列表上宣布。查看基本模板的先前通知。贡献者和pr列表与为上面的发行说明生成的列表相同。如果交叉发布,请确保python announce list是bcc,这样回复就不会发送到该列表。
签出主端口和转发端口文档更改:
$ git checkout -b post-1.19.0-release-update $ git checkout maintenance/1.19.x doc/source/release/1.19.0-notes.rst $ git checkout maintenance/1.19.x doc/changelog/1.19.0-changelog.rst $ git checkout maintenance/1.19.x .mailmap # only if updated for release. $ gvim doc/source/release.rst # Add link to new notes $ git add doc/changelog/1.19.0-changelog.rst doc/source/release/1.19.0-notes.rst $ git status # check status before commit $ git commit -a -m"REL: Update master after 1.19.0 release." $ git push origin HEAD
去github做个公关。