重要

本文档涵盖 IPython 6.0 及更高版本。从 6.0 版本开始，IPython 不再支持与低于 3.3 的 Python 版本（包括所有版本的 Python 2.7）的兼容性。

如果您正在寻找与 Python 2.7 兼容的 IPython 版本，请使用 IPython 5.x LTS 版本并参阅其文档（LTS 是长期支持版本）。

IPython 核心开发人员指南

本指南记录了 IPython 本身的开发。或者，使用 IPython 的第三方工具和库的开发人员应该参阅 第三方工具和库的开发者指南。

有关如何进行开发人员安装的说明，请参阅 安装开发版本。

反向移植拉取请求

所有拉取请求通常应针对 main 进行，如果需要将拉取请求反向移植到早期版本；然后应使用正确的 milestone 标记它。

如果您在合并拉取请求之前使用里程碑标记拉取请求，并且基本引用是 main，那么我们的反向移植机器人应该自动创建一个相应的拉取请求，该请求反向移植到正确的分支上。

如果您有 IPython 存储库的写访问权限，您还可以只提及反向移植机器人来为您完成这项工作。该机器人正在不断发展，因此说明可能有所不同。在撰写本文时，您可以使用

@meeseeksdev[bot] backport [to] <branchname>

该机器人将尝试反向移植当前拉取请求并在可能的情况下发布 PR。

注意

提及机器人时，@ 和 [bot] 应该是可选的，可以省略。

如果无法自动反向移植拉取请求，机器人会在 PR 上告诉您，并在原始 PR 上应用“需要手动反向移植”标签。

IPython 发布流程

本文档包含用于创建 IPython 版本的流程。

方便的是，IPython 存储库的 tools 目录中的 release 脚本自动执行了大部分发布流程。本文档作为发布经理的方便提醒和清单。

在发布过程中，您可能需要以下额外依赖项

  • keyring 访问您的 GitHub 身份验证令牌

  • graphviz 在文档中生成一些图表

  • ghpro 生成统计信息

确保您还具有运行测试所需的所有必需依赖项。

当通过 bash 发布时，您可以尝试 source tools/release_helper.sh，它应该指导您完成大部分流程。

1. 设置环境变量

设置环境变量以记录以前的发布标签、当前发布里程碑、当前发布版本和 git 标签。

这些变量稍后可用于复制/粘贴为脚本问题的答案，而不是在适当的时候输入适当的命令。脚本不直接使用这些变量；因此，无需 export 它们。bash 的格式如下，但请注意，这些值只是一个示例，仅对 5.0 版本有效；您需要为实际进行的版本更新它们

PREV_RELEASE=4.2.1
MILESTONE=5.0
VERSION=5.0.0
BRANCH=main

为了构建的可重复性，我们建议在运行构建之前设置SOURCE_DATE_EPOCH；记录使用的SOURCE_DATE_EPOCH值，因为它可能无法从构建工件中获得。您应该能够使用date +%s来获取格式化的时间戳

SOURCE_DATE_EPOCH=$(date +%s)

2. 创建 GitHub 统计数据并完成发行说明

注意

如果进行 Beta 或 RC 发行，此步骤是可选的。

注意

在生成 GitHub 统计数据之前，请验证所有已关闭的问题和拉取请求都具有适当的里程碑。此搜索在创建 GitHub 统计数据之前应不返回任何结果。

如果是一个主要发行版

  • 将所有拉取请求注释合并到新内容中

    python tools/update_whatsnew.py

  • 更新docs/source/whatsnew/development.rst，以确保其涵盖主要发行版功能

  • 将development.rst的内容移动到versionX.rst，其中X是数字发行版本

  • 生成 GitHub 贡献摘要，可通过以下方式完成

    python tools/github_stats.py --milestone $MILESTONE > stats.rst

    可能需要对stats.rst进行一些手动清理。将清理后的stats.rst结果添加到docs/source/whatsnew/github-stats-X.rst，其中X是数字发行版本（别忘了将其添加到 git 存储库中）。如果创建主要发行版，请创建一个新的github-stats-X.rst文件；如果创建次要发行版，则stats.rst中的内容可以简单地添加到现有github-stats-X.rst文件的顶部。

  • 编辑docs/source/whatsnew/index.rst以列出您刚创建的新github-stats-X文件。

  • 您不需要暂时删除名为development的第一个条目，也不需要在发布后重新添加它，在发布 IPython 的稳定版本时，它将自动隐藏（如果release.py中的_version_extra是一个空字符串）。

    确保统计文件有标题，否则它不会在最终文档中呈现。

要查找重复项并更新.mailmap，请使用

git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f

如果是一个次要发行版，您可能需要手动执行上述某些步骤，并向前移植更改。

3. 确保存储库干净

任何可能出现问题的文件。

使用以下命令删除所有未跟踪的文件

git clean -xfdi

在删除所有未跟踪的文件之前，这将要求确认。确保dist/文件夹干净，以避免因之前的构建尝试而导致任何陈旧构建。

4. 更新发行版本号

编辑IPython/core/release.py以获得当前版本。

尤其是，更新版本号和 _version_extra 内容，位于 IPython/core/release.py。

步骤 5 将自动验证您的更改，但您可能仍希望确保版本号与 pep440 匹配。

尤其是，rc 和 beta 不用 . 分隔，否则 sdist 和 bdist 将显示为不同的版本。例如，候选版本 (rc) 版本的有效版本号为：1.3rc1。请注意，“3”和“r”之间没有分隔符。还要检查环境变量 $VERSION。

您可能只需要修改/注释/取消注释设置 _version_extra 的其中一行

5. 运行 tools/build_release 脚本

运行 tools/build_release 会执行实际发布脚本将执行的所有文件检查和构建。这会进行测试安装，检查构建过程是否正常运行，以及测试发布过程中的其他步骤。

尤其是，build_release 脚本将验证版本号是否与 PEP 440 匹配，以避免在构建上传时出现意外情况。

我们还建议创建文档的测试构建。

6. 创建并推送新标签

提交对 release.py 的更改

git commit -am "release $VERSION" -S
git push origin $BRANCH

（如果您不签名软件包，则省略 -S）

创建并推送标签

git tag -am "release $VERSION" "$VERSION" -s
git push origin $VERSION

（如果您不签名软件包，则省略 -s）

将 release.py 更新回 x.y-dev 或 x.y-maint 提交并推送

git commit -am "back to development" -S
git push origin $BRANCH

（如果您不签名软件包，则省略 -S）

现在签出我们刚创建的标签

git checkout $VERSION

7. 运行发布脚本

运行 release 脚本，此步骤需要当前的轮子、Python >=3.4 和 Python 2.7。

./tools/release

这会生成 tarball 和轮子，并将它们放在 dist/ 文件夹下。在将 wheels 和 sdist 上传到 PyPI 之前，务必在本地对其进行测试。我们不使用通用轮子，因为每个轮子都会安装 ipython2 或 ipython3 脚本，具体取决于为其构建的 Python 版本。使用通用轮子会阻止这种情况。

使用以下命令检查文件的 shasum

shasum -a 256 dist/*

并记下它们，您可能需要它们来更新 conda-forge 配方。重新运行该命令并检查哈希值是否已更改

./tools/release
shasum -a 256 dist/*

使用以下命令实际上传构建结果

./tools/release upload

它应该将它们发布到 archive.ipython.org 和 PyPI。

PyPI/Warehouse 会自动隐藏以前的版本。如果您要上传非稳定版本，请务必登录 PyPI 并取消隐藏以前的版本。

8. 起草一份简短的发布公告

公告应包括

  • 发布亮点

  • 文档中新增功能部分的 html 版本链接

  • 升级或安装提示链接（如果需要）

将公告发布到邮件列表或博客，并从 Twitter 链接。

注意

如果您正在进行 RC 或 Beta，则可以跳过后续步骤。

9. 更新 GitHub 上的里程碑

这些步骤将使里程碑保持最新

  • 关闭刚发布的里程碑

  • 为下一个版本（x, y+1）打开一个新的里程碑，如果里程碑不存在

10. 更新 IPython 网站

IPython 网站应记录新版本

  • 添加发布公告（新闻、公告）

  • 更新当前版本和下载链接

  • 更新文档页面上的链接（特别是对于重大版本）

11. 更新 readthedocs

确保更新 readthedocs，并将最新标签设置为稳定，并检查先前版本是否仍在其自己的标签下构建。

12. 更新 Conda-Forge 原料

按照存储库上的说明进行操作

13. 庆祝！

庆祝发布，并感谢贡献者的工作。干得好！

旧文档

过时的文档仍然可用，并已保留以供存档。

注意

开发者文档曾经在 IPython wiki 上，但现在已经过时。出于历史原因，wiki 仍然可用：旧 IPython GitHub Wiki。