为NumPy贡献 > 发布版本
该文件概述了为NumPy构建二进制发行版所需的内容。
有关构建和发布NumPy和SciPy的当前信息分散在多个地方。应该将其汇总在一个地方,进行更新,并在必要时进行更详细的描述。以下各节列出了所有可以找到有用信息的地方。
INSTALL.rst.txt
release.sh
路面
从源代码构建时,Python 2.7和> = 3.4是当前受支持的版本。每次将代码合并到master时,我们都会针对所有这些版本测试NumPy。二进制安装程序可能可用于这些版本的子集(请参见下文)。
Python 2.7和> = 3.4是我们提供二进制安装程序的版本。支持OS X版本> = 10.6。我们为OSX构建与Python.org Python,系统Python,自制软件和Macports兼容的二进制轮子- 有关详细信息,请参见此OSX轮子构建摘要。
我们在Windows上为Python 2.7、3.4、3.5构建32位和64位轮子。支持Windows XP,Vista,7、8和10。我们使用Appveyor上的MSVC编译器构建NumPy,但我们希望更新为mingw-w64工具链。Windows轮子将ATLAS用于BLAS / LAPACK。
没有提供二进制文件,但是已经报告了在Solaris和BSD上成功构建的版本。
我们将所有精力都放在云基础架构上-因此,此编译器列表用于提供信息并在本地调试构建。有关构建配方的确切来源,请参见numpy轮回购中的.travis.yml
和
appveyor.yml
脚本。注意使用pip可用的软件包。
相同的gcc版本与在每个平台上构建Python本身的版本相同。目前,这意味着:
OS X基于当前使用clang的 travis构建。当使用Python.org安装程序中的Python进行构建时,似乎可以从travis-ci OSX 10.9 VM安全地构建OSX> = 10.6的二进制轮子。
Windows构建使用与之相对应的Python对应的MSVC版本;
Manylinux1轮子使用Manylinux docker映像上提供的gcc。
您将需要Cython来构建二进制文件。Cython将.pyx
NumPy分发中的.c
文件编译为文件。
您将需要numpy-wheels的写入权限才能触发滚轮构建。
python.org或linux发行版中的Python 。
cython(点子)
virtualenv(点子)
摊铺机(点子)
pandoc pandoc.org或linux发行版。
numpy-wheels https://github.com/MacPython/numpy-wheels(克隆)
terryfy https://github.com/MacPython/terryfy(克隆)。
beautifulsoup4(点子)
脱位(点)
奥迪轮(点子)
麻线
您将需要一个个人访问令牌 https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/, 以便脚本可以访问github NumPy存储库。
gitpython(点子)
pygithub(pip)
Virtualenv是一个非常有用的工具,可以保留多个版本的软件包。它在Paver脚本中也用于构建文档。
使用Appveyor构建的适用于32位和64位的Python 2.7、3.4、3.5的Windows轮子;
通过travis-ci构建的双体系结构OSX轮子;
通过travis-ci构建的32位和64位Manylinux1轮子。
有关更多详细信息,请参见numpy wheels构建存储库。
发行说明
变更日志
我们以.zip和.tar.gz格式构建源代码版本。
典型的发布时间表是一个Beta,两个候选版本和一个最终版本。最好首先在邮件列表上讨论时间安排,以便人们按时提交承诺,合并文档Wiki编辑等。设置日期后,创建一个新的maintenance / xyz分支,添加新的空白版本在master分支中记录下一个版本,并更新Trac里程碑。
git clean -fxd
python setup.py bdist
python setup.py sdist
要在正确设置所有内容后实际构建二进制文件,可以使用release.sh脚本。有关构建过程本身的详细信息,最好阅读pavement.py脚本。
注意
针对Beta,候选发行版和最终发行版重复以下步骤。
在进行发行分支之前,应检查是否已删除所有应删除的不赞成使用的代码,并且所有新的不赞成使用的内容在文档字符串或不赞成使用的警告中均注明将删除哪个版本的代码。
需要在三个地方跟踪C API版本
numpy / core / setup_common.py
numpy / core / code_generators / cversions.txt
numpy /核心/include/numpy/numpyconfig.h
该过程分为三个步骤。
如果API已更改,请在setup_common.py中增加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是该发行版的主要和次要版本号。仅当包含文件中的某些功能或宏已被弃用时,才需要将该宏的值从以前的版本中增加。
numpy / core / setup_common.py中的C ABI版本号应仅针对主要版本进行更新。
使用towncrier构建发行说明并提交更改。这将删除所有片段
doc/release/upcoming_changes
并添加doc/release/<version>-note.rst
。请注意,由于最后一个版本(19.2.0)已过时,当前必须从其master分支安装Towncrier。
towncrier –版本“ <版本>” git commit -m“创建发行说明”
检查发行说明是否为最新。
用重点部分更新发行说明。提及以下内容:
主要的新功能
不推荐使用和删除的功能
支持的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
正确设置了变量。
现在,您可以进行发布提交和标记。我们建议您不要立即推送提交或标记,以防万一您需要进行更多清理。我们更愿意推迟标签的推送,直到我们确信这是已发布代码的确切形式为止(请参阅:推送release标签并提交):
git commit -s -m“ REL:释放。” setup.py git标签-s <版本>
该-s
标志构成一个PGP(通常是GPG)签名的标签。请对发布标签进行签名。
发布标签的注释(标签消息)中应具有发布编号。不幸的是,可以在不破坏签名的情况下更改标签的名称,而消息的内容则不能。
请参阅:https://github.com/scipy/scipy/issues/4919签署发布标签的讨论,并https://keyring.debian.org/creating-key.html有关创建,如果你一个GPG密钥的说明没有一个。
为了使您的密钥更容易识别,请考虑使用以下命令将密钥发送到公共密钥服务器:
gpg --send-keys <yourkeyid>
在NumPy 1.10.0中将NPY_RELAXED_STRIDE_CHECKING设置为默认值,并且在开发分支中使用了伪步幅来冒出问题。该 补丁如有必要应进行更新,并应用到发布分支理顺进展。
在setup.py中增加发行版号。候选发布版本应在XYZ格式后附加“ rc1”(或“ rc2”,“ rcN”)。
还要在cversions.txt中创建新版本的哈希,并在numpyconfig.h中定义相应的版本NPY_x_y_API_VERSION
请参阅numpy wheels存储库。
在该存储库中,编辑文件:
.travis.yml
;
appveyor.yml
。
在这两种情况下,都将BUILD_COMMIT
变量设置为当前的发行标签-例如v1.11.1
。
确保已按下释放标签。
触发构建做一个提交您的修改来.travis.yml
和
appveyor.yml
到仓库:
cd /path/to/numpy-wheels
# Edit .travis.yml, appveyor.yml
git commit
git push
轮子一旦制成,就会出现在Rackspace容器中,该容器指向:
HTTP地址可能会首先更新,您应在构建完成后等待15分钟,然后再获取二进制文件。
做:
cd doc/
make dist
检查文档是否处于可构建状态。然后,在标记后,在numpy / doc存储库中创建文档的存档:
# 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,
# and commit the changes
git -C dist/merge commit -a "Add documentation for <version>"
# Push to numpy/doc repo
git -C push
车轮和源应该上传到PyPI。
您应该首先上传车轮,最后上传源格式,以确保pip用户在期望使用二进制车轮时不会意外获得源安装。
您可以使用https://github.com/MacPython/terryfy中的wheel-uploader
脚本
自动执行此操作。这是推荐的咒语,用于下载所有Windows,Manylinux,OSX轮子并上传到PyPI。
NPY_WHLS=~/wheelhouse # local directory to cache wheel downloads
CDN_URL=https://3f23b170c54c2533c070-1c8a9b3114517dc5fe17b7c3f8c63a43.ssl.cf2.rackcdn.com
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键对车轮进行了签名。别忘了在源代码压缩包之前上载这些轮子,因此人们没有时间从预期的二进制安装切换到从PyPI进行源安装。
有两种方法可以在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_INFO文件。也可以通过此界面上载源tarball。
最后,现在您确信此标记正确定义了您发布的源代码,可以将其推送并释放到github的提交:
git push # Push release commit
git push upstream <version> # Push tag named <version>
其中upstream
点到主https://github.com/numpy/numpy.git
库。
带有下载站点链接的发行公告应放在scipy.org主页的侧边栏中。
scipy.org应该是https://github.com/scipy/scipy.org上的PR 。需要修改的文件是www/index.rst
。搜索News
。
该版本应在NumPy和SciPy的邮件列表中进行公告,以进行python公告,也可能在Matplotlib,IPython和/或Pygame的列表中进行公告。
在beta / RC阶段,应在邮件列表中明确要求使用其他几个库(SciPy / Matplotlib / Pygame)测试二进制文件。
给LWN的编辑发送电子邮件,以使他们知道该版本。方向:https: //lwn.net/op/FAQ.lwn#contact
该文件包含Linux上NumPy 1.14.5版本的演练。可以将命令复制到命令行中,但是请确保使用正确的版本替换1.14.5。
请注意,在下面的代码段中,upstream
指的是github上的根存储库以及origin
您个人帐户中的fork。如果您尚未分叉存储库,而只是在本地将其克隆,则可能需要进行调整。您还可以编辑.git/config
和添加(upstream
如果尚不存在)。
必须将已为此版本标记的更改反向移植到maintenance / 1.14.x分支。
该文件doc/changelog/1.14.5-changelog.rst
应进行更新以反映更改和贡献者的最终列表。可以通过以下方式生成此文本:
$ python tools/changelog.py $GITHUB v1.14.4..maintenance/1.14.x > doc/changelog/1.14.5-changelog.rst
其中GITHUB
包含您的github访问令牌。该文本也可以附加到doc/release/1.14.5-notes.rst
版本更新中,尽管不是新发行版本(如)1.14.0
,因为版本的更新日志*.0
往往会太长。该doc/source/release.rst
文件还应该使用指向新发行说明的链接进行更新。这些更改应提交给维护分支,以后再转发给master。
填写发行说明,以doc/release/1.14.5-notes.rst
进行重大更改。
检出该发行版的分支,确保它是最新的,并清理存储库:
$ git checkout maintenance/1.14.x
$ git pull upstream maintenance/1.14.x
$ git submodule update
$ git clean -xdfq
如HOWTO_RELEASE中所述,编辑pavement.py和setup.py:
$ gvim pavement.py setup.py
$ git commit -a -m"REL: NumPy 1.14.5 release."
完整性检查:
$ python runtests.py -m "full" # NumPy < 1.17 only
$ python3 runtests.py -m "full"
将此发行版直接推到维护分支的末端。这需要对numpy存储库的写许可权:
$ git push upstream maintenance/1.14.x
例如,请参见1.14.3 REL提交:https : //github.com/numpy/numpy/commit/73299826729be58cec179b52c656adfcaefada93。
Paver用于构建源发行版。它将创建release
和
release/installers
目录,并将*.zip
和*.tar.gz
版本发布放入后者。
$ python3 -m cython --version # check for correct cython version
$ paver sdist # sdist will do a git clean -xdf, so we omit that
通过将numpy-wheels存储库指向此提交来触发Wheels构建。这可能需要一段时间。numpy-wheels存储库是从https://github.com/MacPython/numpy-wheels克隆的 。从拉动开始,因为其他人可能已经访问和更改了存储库,而推动将失败:
$ cd ../numpy-wheels
$ git pull upstream master
$ git branch <new version> # only when starting new numpy version
$ git checkout v1.14.x # v1.14.x already existed for the 1.14.4 release
编辑.travis.yml
和.appveyor.yml
文件以确保它们具有正确的版本,并为REL
上面为创建的提交放入提交哈希BUILD_COMMIT
,请参见v1.14.3中的_example :
$ gvim .travis.yml .appveyor.yml
$ git commit -a
$ git push upstream HEAD
现在等等。如果您对花费的时间感到紧张–构建可能需要几个小时–您可以通过以下链接检查构建进度:https://github.com/MacPython/numpy-wheels提供的链接来检查travis和appveyor构建状态。在继续操作之前,请检查是否已构建并上传了所有需要的车轮。https://wheels.scipy.org当前应该有22个 ,对于Mac为4个,对于Windows为8个,对于Linux为10个。请注意,有时某些构建(例如测试)会由于不相关的原因而失败,因此您需要重新启动它们。
成功安装好所有轮子之后,请使用存储库wheel-uploader
中的下载它们terryfy
。如果您还没有的话,可以从https://github.com/MacPython/terryfy克隆terryfy存储库
。也可以使用来上传车轮wheel-uploader
,但是我们更愿意将所有车轮下载到../numpy/release/installers
目录中,然后再使用进行上传twine
:
$ cd ../terryfy
$ git pull upstream master
$ CDN_URL=https://3f23b170c54c2533c070-1c8a9b3114517dc5fe17b7c3f8c63a43.ssl.cf2.rackcdn.com
$ NPY_WHLS=../numpy/release/installers
$ ./wheel-uploader -u $CDN_URL -n -v -w $NPY_WHLS -t win numpy 1.14.5
$ ./wheel-uploader -u $CDN_URL -n -v -w $NPY_WHLS -t manylinux1 numpy 1.14.5
$ ./wheel-uploader -u $CDN_URL -n -v -w $NPY_WHLS -t macosx numpy 1.14.5
如果您经常这样做,请考虑将CDN_URL和NPY_WHLS设置为默认环境的一部分。
一旦轮子被正确地构建和下载,请返回维护分支中的numpy存储库并标记REL
提交,并使用gpg密钥对其进行签名:
$ git tag -s v1.14.5
您应该将您的公共gpg密钥上传到github,以便该标签在此处显示为“已验证”。
检查其中的文件release/installers
具有正确的版本,然后将标签推入上游:
$ git push upstream v1.14.5
我们一直等到这一点才推送标签,因为它是公共标签,在推送之后不应该更改。
REL
向numpy维护分支添加另一个提交,该分支将ISREALEASED
标志重置
为False
并增加版本计数器:
$ gvim pavement.py setup.py
创建下一个发行版本的发行说明,并对其进行编辑以设置版本:
$ cp doc/release/template.rst doc/release/1.14.6-notes.rst
$ gvim doc/release/1.14.6-notes.rst
$ git add doc/release/1.14.6-notes.rst
将新的发行说明添加到文档发行列表:
$ gvim doc/source/release.rst
提交结果:
$ git commit -a -m"REL: prepare 1.14.x for further development"
$ git push upstream maintenance/1.14.x
使用上载到PyPI twine
。twine
在最近的PyPI更改之后,需要一个的最新版本,1.11.0
此处使用的是该版本。
$ cd ../numpy
$ twine upload release/installers/*.whl
$ twine upload release/installers/numpy-1.14.5.zip # Upload last.
如果其中一个命令在中间中断(这很常见),则可能需要有选择地上载其余文件,因为PyPI不允许同一文件上载两次。源文件应最后上传,以避免在运行过程中如果pip用户访问文件时出现同步问题。请注意,PyPI仅允许单个源分发,这里我们选择了zip存档。
转到https://github.com/numpy/numpy/releases,应该有一个,单击它,然后单击该标签的编辑按钮。有两种添加文件的方法,一种是使用可编辑的文本窗口,另一种是二进制上传。v1.14.5
tag
将release/README.md
文件内容剪切并粘贴到文本窗口中。
上载release/installers/numpy-1.14.5.tar.gz
为二进制文件。
上载release/installers/numpy-1.14.5.zip
为二进制文件。
上载release/README.rst
为二进制文件。
上载doc/changelog/1.14.5-changelog.rst
为二进制文件。
如果这是预发行版本,请检查预发行按钮。
点击底部的按钮。{Publish,Update} release
仅对于最终版本,才需要执行此步骤,对于预发布版本,可以跳过此步骤。将存储库克隆到
并使用新文档进行更新:make merge-doc
numpy/doc
doc/build/merge
$ pushd doc
$ make dist
$ make merge-doc
$ popd
如果发行版系列是新发行版,则需要doc/build/merge/index.html
在“在此处插入”注释之后的首页中添加一个新部分
:
$ gvim doc/build/merge/index.html +/'insert here'
否则,只有zip
和pdf
链接应使用新标签名称进行更新:
$ gvim doc/build/merge/index.html +/'tag v1.14'
您可以在浏览器中“测试运行”新文档,以确保链接有效:
$ firefox doc/build/merge/index.html
一切看起来令人满意后,提交并上传更改:
$ pushd doc/build/merge
$ git commit -am"Add documentation for v1.14.5"
$ git push
$ popd
假设您已分叉https://github.com/scipy/scipy.org:
$ cd ../scipy.org
$ git checkout master
$ git pull upstream master
$ git checkout -b numpy-1.14.5
$ gvim www/index.rst # edit the News section
$ git commit -a
$ git push origin HEAD
现在转到叉子,并为分支请求拉取请求。
该发布应在numpy-discussion,scipy-devel,scipy-user和python-announce-list邮件列表中宣布。请查看以前的公告以获取基本模板。贡献者列表和PR列表与上述发行说明中生成的列表相同。如果您进行交叉发布,请确保python-announce-list为BCC,以便不会将回复发送到该列表。
向前移植文档更改doc/release/1.14.5-notes.rst
,
doc/changelog/1.14.5-changelog.rst
并将发行说明添加到
doc/source/release.rst
。