释放指南

本文档仅与Matplotlib版本管理器相关。

为正在进行Matplotlib发行版的开发人员提供的指南。

注解

这假设规范存储库的只读远程 remote 读/写遥控器是 DANGER

所有版本

测试

我们使用 Travis CI 用于持续集成。在准备发布时，最终标记的提交应在上载之前在本地进行测试：：

pytest -n 8 .

此外，应进行以下试验并进行手动检查：

python tools/memleak.py agg 1000 agg.pdf

此外，应运行并手动检查以下各项，但当前已损坏：

pushd examples/tests/
python backend_driver_sgskip.py
popd

GitHub 统计

我们通过API自动从GitHub中提取GitHub问题、PRs和作者。复制当前 doc/users/github_stats.rst 到 doc/users/prev_whats_new/github_stats_X.Y.Z.rst ，更改文件顶部的链接目标，并删除末尾的“Previous GitHub Stats”部分。

例如，从v3.2.0更新到v3.2.1时：

cp doc/users/github_stats.rst doc/users/prev_whats_new/github_stats_3.2.0.rst
$EDITOR doc/users/prev_whats_new/github_stats_3.2.0.rst
# Change contents as noted above.
git add doc/users/prev_whats_new/github_stats_3.2.0.rst

然后重新生成更新的统计信息：

python tools/github_stats.py --since-tag v3.2.0 --milestone=v3.2.1 --project 'matplotlib/matplotlib' --links > doc/users/github_stats.rst

检查并提交更改。某些问题/PR标题可能无效（最常见的问题是 * 这被解释为未关闭的标记）。

注解

确保根据githubapi进行身份验证。如果你不这样做，你将被GitHub阻止超过API速率限制。您可以通过以下两种方式之一进行身份验证：

  • 使用 keyring 包裹； pip install keyring 然后在运行stats脚本时，系统会提示您输入用户名和密码，这些用户名和密码将存储在系统keyring中，或者，
  • 使用个人访问令牌；生成新令牌 on this GitHub page 与 repo:public_repo 范围和放置令牌 ~/.ghoauth .

更新和验证文档

合并 *-doc 分支

合并最近的“文档”分支（例如。， v3.2.0-doc )到要标记的分支中，并删除GitHub上的doc分支。

更新“新增功能”和“API更改”

在标记主要版本和次要版本之前，应该更新“新增内容”和“API更改”列表。微版本不需要这样做。

为了“最新消息”，

  1. 将当前内容复制到中的文件 doc/users/prev_whats_new
  2. 合并所有文件 doc/users/next_whats_new/ 进入之内 doc/users/whats_new.rst 删除个别文件
  3. 在顶部注释出下一个what's new glob

类似地，“API更改”，

  1. 将当前api更改复制到文件是 doc/api/prev_api_changes
  2. 合并最新版本中的所有文件 doc/api/api_changes_X.Y 进入之内 doc/api/api_changes.rst
  3. 在顶部注释掉最新的API更改。

在这两种情况下，第3步必须在发布后立即取消。

验证文档是否生成

最后，确保文档构建干净：

make -Cdoc O=-j$(nproc) html latexpdf

创建文档后，检查所有链接（内部和外部）是否仍然有效。我们使用 linkchecker 对于这个，它还没有被移植到Python3。您将需要创建一个Python2环境 requests==2.9.0 和链接检查器：

conda create -p /tmp/lnkchk python=2 requests==2.9.0
source activate /tmp/lnkchk
pip install linkchecker
pushd doc/build/html
linkchecker index.html --check-extern
popd

解决可能出现的任何问题。在Circle CI上检查内部链接，这应该只标记失败的外部链接。

创建发布提交和标记

要创建标记，首先使用提交消息中非常简短的一组发行说明创建一个空提交：

git commit --allow-empty

然后用正文消息中的相同文本创建一个带签名和注释的标记：：

git tag -a -s v2.0.0

它将提示您输入GPG密钥密码和注释。对于预发布，重要的是遵循 PEP 440 以便构建工件在PyPI中正确排序。

为了防止任何从Github下载tarball的下游构建器出现问题，必须将所有分支从带有标记的commit中移开。 [1]:

git commit --allow-empty

最后，将标记推送到GitHub:：

git push DANGER master v2.0.0

恭喜你，最可怕的部分完成了！

[1]

Github提供的tarball使用 git archive . 我们使用 versioneer 它使用格式字符串 lib/matplotlib/_version.py 拥有 git 插入导出提交的引用列表（请参见 .gitattributes 对于配置）。然后使用此字符串 versioneer 当用户从tarball安装时，根据git标签生成正确的版本。但是，如果有一个分支指向标记的提交，那么分支名称也将包含在tarball中。当树枝最终移动时，任何在树枝移动之前如何检查tarball散列的人都将得到不正确的散列。

要生成GitHub使用的文件，请执行以下操作：

git archive v2.0.0 -o matplotlib-2.0.0.tar.gz --prefix=matplotlib-2.0.0/

如果这是最终版本，也要创建一个“Doc”分支（对于预发布不这样做）：：

git branch v2.0.0-doc
git push DANGER v2.0.0-doc

如果这是一个主要的或次要的版本，也创建一个bug修复分支（一个微版本将从此分支中剪切）：

git branch v2.0.x

在这个分支上，联合国从 更新和验证文档 . 然后：：

git push DANGER v2.0.x

发布管理/doi

通过 GitHub UI ，将新推送的标记转换为释放。如果这是一个预发布，请记住将其标记为这样。

对于最终版本，还可以从 zenodo （一旦按下标签，它将自动生成一个标签）。将doi post fix和版本添加到中的字典中 tools/cache_zenodo_svg.py 然后运行脚本。

这将把新的svg下载到 _static 目录中的文档和编辑 doc/citing.rst . 提交新的svg，更改为 tools/cache_zenodo_svg.py ，以及 doc/citing.rst 到verdoc分支并推送到GitHub。:

git checkout v2.0.0-doc
$EDITOR tools/cache_zenodo_svg.py
python tools/cache_zenodo_svg.py
$EDITOR doc/citing.html
git commit -a
git push DANGER v2.0.0-doc:v2.0.0-doc

构建二进制文件

我们通过PyPI分发macOS、Windows和许多Linux轮子以及源代码tarball。一旦标签被推送到GitHub，大多数构建器都会自动触发：

  • Mac和manylinux轮子是在Travis CI上建造的。生成由中定义的GitHub操作触发 .github/workflows/wheels.yml ，车轮将在 matplotlib-wheels repo .
  • Windows轮子是由Christoph Gohlke自动构建的，并将 available at his site 一旦建成。
  • auto tick bot应该在 conda-forge feedstock . 审查和合并（如果你有权力）。

警告

因为这是自动化的，所以如中所述，将所有分支从标记中移开是非常重要的 创建发布提交和标记 .

如果是最终版本，应联系以下下游包装商：

  • 德比
  • 费多拉
  • 拱门
  • 圣母
  • 麦克波特
  • 自酿啤酒
  • 连续体
  • 想到

这可以在收集所有二进制文件并上传到pypi之前完成。

分发并上传到PyPI

一旦你收集了所有的轮子（预计这需要一天的时间），生成tarball:：

git checkout v2.0.0
git clean -xfd
python setup.py sdist

把所有的轮子复制到 dist 目录。首先，检查dist文件是否正常：

twine check dist/*

然后使用 twine 要将所有文件上载到pypi:：

twine upload -s dist/matplotlib*tar.gz
twine upload dist/*whl

恭喜你，你已经完成了第二个最可怕的部分！

构建和部署文档

若要生成文档，必须安装有标记的版本，但必须从 ver-doc 分支机构。一个简单的安排方法是：

pip install matplotlib
pip install -r requirements/doc/doc-requirements.txt
git checkout v2.0.0-doc
git clean -xfd
make -Cdoc O=-j$(nproc) html latexpdf LATEXMKOPTS="-silent -f"

它将构建文档的HTML和PDF版本。

构建的文档存在于 matplotlib.github.com 储存库。将更改推到master会自动更新网站。

文档按版本组织。最新稳定版本的文档总是在树的根目录下。在该目录下，有包含旧版本文档的目录。当前主控形状的文档建立在Circle CI上，并推送到 devdocs 存储库。这些可在 matplotlib.org/devdocs .

假设您已将此存储库签出到与matplotlib:相同的目录中：

cd ../matplotlib.github.com
mkdir 2.0.0
rsync -a ../matplotlib/doc/build/html/* 2.0.0
cp ../matplotlib/doc/build/latex/Matplotlib.pdf 2.0.0

它将复制生成的文档。如果这是最终版本，也要替换顶级文档：

rsync -a 2.0.0/* ./

您需要手动编辑 versions.html 以显示最后3个标记的版本。现在提交并将所有内容推送到Github:：

git add *
git commit -a -m 'Updating docs for v2.0.0'
git push DANGER master

恭喜你已经完成了第三个最可怕的部分！

如果您有访问权限，请清除Cloudflare缓存。

GitHub处理推送和更新实时网页通常需要5-10分钟（记住清除浏览器缓存）。

宣布

最后一步是向世界宣布释放。发行说明的简短版本以及确认应发送至

对于最终版本，还应将公告发送到numpy/scipy/scikit图像邮件列表。

此外，还应在社交网络上发布公告（通过 @matplotlib account, any other via personal accounts). NumFOCUS 应联系以纳入他们的通讯。