发布指南

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

面向正在发布 Matplotlib 的开发人员的指南。

笔记

这假设规范存储库的只读远程是 remote并且读/写远程是DANGER

测试

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

pytest -n 8 .

此外，应运行并手动检查以下测试：

python tools/memleak.py agg 1000 agg.pdf

此外，应运行并手动检查以下内容，但目前已损坏：

pushd examples/tests/
python backend_driver_sgskip.py
popd

GitHub统计

我们通过 API 自动从 GitHub 中提取 GitHub 问题、PR 和作者。将当前复制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 标题可能不是有效的 reST（最常见的问题是*被解释为未封闭标记）。

笔记

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

• 使用keyring包；然后在运行 stats 脚本时，系统会提示您输入用户名和密码，它们将存储在您的系统密钥环中，或者，pip install keyring

• 使用个人访问令牌；在这个 GitHub 页面上生成一个带有repo:public_repo 范围的新令牌，并将令牌放在~/.ghoauth.

更新和验证文档

合并*-doc分支

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

更新安全策略中支持的版本

制作主要或次要版本时，请在SECURITY.md. 通常，这可能是一个或两个以前的次要版本，但取决于版本管理器。

更新发行说明

有什么新鲜事

只有主要和次要版本才需要。错误修复版本不应该有新功能。

将所有文件的内容合并doc/users/next_whats_new/ 到一个文件中doc/users/prev_whats_new/whats_new_X.Y.0.rst 并删除单个文件。

API 更改

主要用于主要和次要版本。我们有时可能会在错误修复版本中更改 API。

将所有文件的内容合并doc/api/next_api_changes/ 到一个文件中doc/api/prev_api_changes/api_changes_X.Y.Z.rst 并删除单个文件。

发行说明 TOC

更新doc/users/release_notes.rst：

• 对于主要和次要版本，添加一个新部分

  X.Y
  ===
  .. toctree::
      :maxdepth: 1
  
      prev_whats_new/whats_new_X.Y.0.rst
      ../api/prev_api_changes/api_changes_X.Y.0.rst
      prev_whats_new/github_stats_X.Y.0.rst
  

• 对于错误修复版本，将 GitHub 统计信息和（如果存在）API 更改添加到现有的 XY 部分

  ../api/prev_api_changes/api_changes_X.Y.Z.rst
  prev_whats_new/github_stats_X.Y.Z.rst
  

更新版本切换器

更新doc/_static/switcher.json。如果是次要版本，X.Y.Z创建一个新条目，并更改 stable 的名称 。如果是主要版本，请更改名称并为以前的稳定版本添加新版本。version: X.Y.(Z-1)name: stable/X.Y.ZX.Y.0name: devel/X.(Y+1)name: stable/X.Y.0

验证文档是否构建

最后，确保文档构建干净

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 上检查内部链接，这应该只标记失败的外部链接。

更新 SECURITY.md 中支持的版本

对于次要版本版本，请更新表格SECURITY.md以指定支持当前主要版本系列中的 2 个最新次要版本。

对于主要版本版本，请更新表格SECURITY.md以指定仍支持先前主要版本系列中的最后一个次要版本。放弃对主要版本系列的最后一个版本的支持将临时处理。

创建发布提交和标签

要创建标签，首先创建一个空提交，并在提交消息中包含一组非常简洁的发行说明

git commit --allow-empty

然后在正文消息中创建一个带有相同文本的签名、注释标签

git tag -a -s v2.0.0

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

为了防止从 GitHub 下载 tarball 的任何下游构建器出现问题，将所有分支从带有标签[ 1 ]的提交中移开是很重要的：

git commit --allow-empty

最后，将标签推送到 GitHub：

git push DANGER main v2.0.0

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

[ 1 ]

GitHub 提供的 tarball 是使用git archive生成​​的。我们使用setuptools_scm，它使用格式字符串 lib/matplotlib/_version.py来git插入导出提交的引用列表（请参阅 .gitattributes配置）。然后，当用户从 tarball 安装时，此字符串将用于setuptools_scm根据 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

如果这是一个主要或次要版本，还要创建一个错误修复分支（将从该分支中​​删除一个微版本）：

git branch v2.0.x

在此分支上取消注释更新中的 glob 并验证文档。接着

git push DANGER v2.0.x

发布管理/DOI

通过GitHub UI，将新推送的标签转换为发布。如果这是预发行版，请记住将其标记为预发行版。

对于最终版本，还可以从zenodo获取 DOI （一旦推送标签，它将自动生成一个）。将 doi 后缀和版本添加到字典中 tools/cache_zenodo_svg.py并运行脚本。

这会将新的 svg 下载到_static文档中的目录并编辑doc/citing.rst. 将新的 svg、对 的更改tools/cache_zenodo_svg.py和 doc/citing.rst对 VER-doc 分支的更改提交并推送到 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，大多数构建器应该会自动触发：

• Windows、macOS 和 manylinux 轮子是基于 GitHub Actions 构建的。构建由 中定义的 GitHub Action 触发 .github/workflows/cibuildwheel.yml，并且轮子将作为构建的工件提供。

• 替代的 Windows 轮子由 Christoph Gohlke 自动制造，建成后将在他的网站上提供。

• auto-tick 机器人应该向conda-forge feedstock打开一个拉取请求。审查和合并（如果你有能力）。

警告

因为这是自动化的，所以将所有分支从标签中删除是非常重要的，如创建发布提交和标签中所述。

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

• Debian

• 软呢帽

• 拱

• 琴图

• 麦克波特

• 家酿

• 连续体

• 深思熟虑

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

进行分发并上传到 PyPI

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

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

并将所有轮子复制到dist目录中。首先，检查dist文件是否OK

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="-t release -j$(nproc)" html latexpdf LATEXMKOPTS="-silent -f"

这将构建文档的 html 和 pdf 版本。

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

文档按版本组织。树的根部始终是最新稳定版本的文档。在此之下，有一些目录包含旧版本的文档。当前 main 的文档基于 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

这将复制构建的文档。如果这是最终版本，请将 stable子目录链接到最新版本：

rsync -a 2.0.0/* ./
rm stable
ln -s 2.0.0/ stable

您将需要手动编辑versions.html以显示最后 3 个标记的版本。您还需要进行编辑sitemap.xml以包含新发布的版本。现在提交并将所有内容推送到 GitHub

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

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

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

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

宣布

最后一步是向全世界宣布发布。应将发布说明的简短版本以及致谢发送至

• matplotlib用户@python 。组织

• matplotlib-devel @ python 。组织

• matplotlib-announce @ python 。组织

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

此外，应在社交网络上发布公告（Twitter 通过@matplotlib帐户，任何其他通过个人帐户）。 应联系NumFOCUS以将其包含在他们的时事通讯中。

康达包

Matplotlib 项目本身不发布 conda 包。特别是，Matplotlib 发布管理器不负责 conda 打包。

有关用于 conda-forge 的 Matplotlib 包装的信息，请参阅 https://github.com/conda-forge/matplotlib-feedstock。