Following system colour scheme Selected dark colour scheme Selected light colour scheme

Python 增强提案

PEP 102 – Python 微版本发布指南

作者:
Anthony Baxter <anthony at interlink.com.au>, Barry Warsaw <barry at python.org>, Guido van Rossum <guido at python.org>
状态:
已取代
类型:
信息
创建:
2002年1月9日
后记:

取代者:
101
目录

替换说明

虽然本 PEP 中的任务清单规模比 PEP 101 中的清单要小很多，但事实证明它不足以证明信息重复的合理性，并且还存在其中一份副本可能过时的风险。因此，本 PEP 已经不再维护，微版本发布的内容已完全涵盖在 PEP 101 中。

摘要

发布 Python 版本是一个繁琐的过程，即使对于经验丰富的发布者来说，也至少需要半天时间。直到最近，大部分（如果不是全部）的负担都由 Guido 自己承担。但是最近的几个版本都是由其他人发布的，因此本 PEP 试图在一个地方收集发布 Python 修补程序版本所需的所有步骤。

主要 Python 版本发布流程在 PEP 101 中有详细说明，本 PEP 只是 PEP 101 的简化版，只包含与微版本发布（也称为补丁发布或 bug 修复发布）相关的部分。

本指南组织为一个食谱，您可以将其打印出来，并在完成每个步骤时打勾。

如何发布版本

以下列出了发布 Python 版本的步骤。一些步骤比其他步骤更模糊，因为几乎无法自动完成（例如，编写 NEWS 项）。如果某一步通常由专家执行，则会给出该专家的姓名。否则，假设该步骤由发布经理（RM）执行，发布经理是负责执行发布的人员。当然，在下面几乎所有提到 RM 的地方，BDFL 也能完成该步骤！

XXX：我们应该包含一个依赖关系图来说明哪些步骤可以并行进行，或者哪些步骤依赖于其他步骤。

在下面的示例中，我们使用以下约定。当给出版本号时，它将采用 X.Y.MaA 的形式，例如 Python 2.1.2 发布候选版本 1 为 2.1.2c1，其中“a” == alpha，“b” == beta，“c” == 发布候选版本。最终版本在 CVS 中标记为“releaseXYZ”。微版本发布是从主要版本的维护分支进行的，例如 Python 2.1.2 是从 release21-maint 分支创建的。

  1. 发送电子邮件到 python-dev@python.org，说明即将开始发布。
  2. 对维护分支的签入进行冻结。此时，除了 RM 之外，任何人都不应该对分支进行任何提交（或其 duly assigned agents，即 BDFL Guido，文档的 Fred Drake，或 Windows 的 Thomas Heller）。如果 RM 出错，并且必须对分支进行紧急的最后一分钟更改，这将意味着 Fred 和 Thomas 需要加班。因此，请尽量避免这种情况！
  3. 在分支上，更改 Include/patchlevel.h 中的两个地方，以反映您刚刚创建的新的版本号。您需要更改 PY_VERSION 宏，以及 PY_VERSION 上方的一个或多个版本子部分宏，具体取决于情况。
  4. 将 Misc/RPM/python-2.3.spec 中的“%define version”行更改为与上面更改后的 PY_VERSION 相同的字符串。例如
    %define version 2.3.1

    您可能还想将 %define release 行重置为‘1pydotorg’，如果它不是这样的话。

  5. 如果您要更改 Python 版本号（例如，从 Python 2.1.1 更改为 Python 2.1.2），您还需要更新 README 文件，该文件顶部有一个大型横幅，声明其标识。如果您只是发布一个新的 alpha 或 beta 版本，请不要这样做，但如果您要发布一个新的微版本、次要版本或主要版本，请这样做。
  6. LICENSE 文件也需要更改，因为它包含对版本号的多个引用。对于 README 文件来说，更改这些内容对于新的微版本、次要版本或主要版本是必要的。

    LICENSE 文件包含一个表格，描述了 Python 的法律传承；您应该添加一个条目，用于您现在要发布的 X.Y.Z 版本。您应该在 CVS 主干上的 LICENSE 文件中也更新此表格。

  7. 当年份发生变化时，需要在许多地方更新版权声明，包括 README 和 LICENSE 文件。
  8. 对于 Windows 构建，需要更新其他文件。

    PCbuild/BUILDno.txt 包含 Windows 构建号，请参阅此文件中的说明，了解如何更改它。保存项目文件 PCbuild/pythoncore.dsp 会导致 PCbuild/pythoncore.dsp 也发生变化。

    PCbuild/python20.wse 设置 Windows 安装程序版本资源（在您右键单击安装程序 .exe 并选择属性时显示），并且还包含 Python 版本号。

    （在 2.3.2 版本之前，需要手动编辑 PC/python_nt.rc，此步骤现在由构建过程自动完成。）

  9. 在开始发布过程后，接下来最重要的事情是更新 Misc/NEWS 文件。Thomas 需要它来完成 Windows 发布，并且他喜欢熬夜。此步骤可能非常乏味，因此最好在创建分支后立即开始，甚至在创建分支之前就开始。越早越好（但请再次注意，在发布完成之前，请注意新的签入！）

    添加此版本中的新功能。例如，如果我们要发布 2.2a3，则文件顶部必须有一节内容解释“Python 2.2a3 中的新功能”。它之后将是一节内容为“Python 2.2a2 中的新功能”。

    请注意，您希望开发人员在将新功能添加到主干时，也相应地更新 NEWS 文件。您无法确定，因此请仔细检查。如果您是 Unix 爱好者，则需要向 Thomas 核实 Windows 上的更改，向 Jack Jansen 核实 Mac 上的更改。

    以下命令可以帮助您（但请替换正确的 -r 标签！）

    % cvs log -rr22a1: | python Tools/scripts/logmerge.py > /tmp/news.txt

    也就是说，您正在打印从上一个版本到现在的所有 cvs 日志条目。然后，您可以浏览 news.txt 文件，查找要添加到 NEWS 中的有趣内容。

  10. 将 NEWS 更改签入维护分支。很容易忘记更新此文件中的发布日期！
  11. 签入对 IDLE 的 NEWS.txt 的任何更改。更新 Lib/idlelib/NEWS.txt 中的标题，以反映其发布版本和日期。更新 Lib/idlelib/idlever.py 中的 IDLE 版本，使其匹配。
  1. 发布过程开始后，需要根据 PEP 101 中的说明，构建文档并发布到 python.org。

    请注意，Fred 负责将文档更改从主干合并到分支，以及在清理阶段将任何分支更改从分支合并到主干。基本上，如果是在 Doc/ 中，Fred 会处理。

  2. Thomas 使用 MSVC 6.0 SP5 编译所有内容，并将 python23.chm 文件移动到 src/chm 目录中。然后使用 Wise Installation System 生成安装程序可执行文件。

    安装程序包含 MSVC 6.0 运行时文件 MSVCRT.DLL 和 MSVCIRT.DLL。如果从安装程序构建的机器上的系统目录获取这些文件，会导致灾难，因此必须确保这些文件来自 MSVC SP5 CD 中的 VCREDIST.EXE 可再发行软件包。VCREDIST.EXE 必须使用 winzip 解压缩，并且 Wise Installation System 会提示您输入目录。

    构建安装程序后，应使用 winzip 打开它，并再次提取 MS dll，并检查其版本号是否与从 VCREDIST.EXE 解压缩的版本号相同。

    Thomas 将此文件上传到 starship。然后，他向 RM 发送通知，其中包含 Windows 可执行文件的位置和 MD5 校验和。

    请注意，Thomas 创建 Windows 可执行文件可能会在分支上生成更多提交。Thomas 将负责将 Windows 特定的更改从主干合并到分支，以及从分支合并到主干。

  3. Sean 执行 Red Hat 魔法，生成一组 RPM。他将这些文件上传到 python.org。然后，他向 RM 发送通知，其中包含 RPM 的位置和 MD5 校验和。
  4. 现在开始构建！

    现在，您已准备好构建源代码 tarball。首先 cd 到分支的工作目录。例如，% cd …/python-22a3

  5. 在此目录中执行“cvs update”。请勿包含 -A 标志！

    您应该看不到任何“M”文件，但可能会看到几个“P”和/或“U”文件。也就是说，您的工作目录中最好不要有任何未提交的更改，但您可能会获取 Fred 或 Thomas 的一些最后一分钟更改。

  6. 现在使用诸如“rXYMaZ”之类的符号名称标记分支，例如 r212
    % cvs tag r212

    确保只标记 Python CVS 树的 python/dist/src 子目录！

  7. 更改为一个中立目录，即可以进行分支的全新、原始 cvs 导出的目录。您将在该位置创建一个新目录，名为“Python-X.Y.M”。执行标记分支的 CVS 导出。
    % cd ~
% cvs -d cvs.sf.net:/cvsroot/python export -rr212 \
                      -d Python-2.1.2 python/dist/src
  8. 生成 tarball。请注意，我们没有在 tar 命令上使用“z”选项，因为 1）据我们所知，这只有 GNU tar 支持，2）我们将最大限度地压缩，这是一个不受支持的选项。我们生成 tar.gz 和 tar.bz2 两种格式，因为后者的压缩率大约是前者的 1/6。
    % tar -cf - Python-2.1.2 | gzip -9 > Python-2.1.2.tgz
% tar -cf - Python-2.1.2 | bzip2 -9 > Python-2.1.2.tar.bz2
  9. 计算您刚刚创建的 tgz 和 tar.bz2 文件的 MD5 校验和
    % md5sum Python-2.1.2.tgz

    请注意，如果您没有 md5sum 程序，则 Tools/scripts/md5sum.py 文件中有一个 Python 替代程序。

  10. 为每个文件创建 GPG 密钥。
    % gpg -ba Python-2.1.2.tgz
% gpg -ba Python-2.1.2.tar.bz2
% gpg -ba Python-2.1.2.exe
  11. 现在，您需要执行一个非常重要的步骤，即检查您刚刚创建的 tarball，以确保完全干净、原始的构建通过回归测试。以下是最佳步骤
    % cd /tmp
% tar zxvf ~/Python-2.1.2.tgz
% cd Python-2.1.2
% ls
(Do things look reasonable?)
% ./configure
(Loads of configure output)
% make test
(Do all the expected tests pass?)

    如果测试通过，那么您可以放心地认为 tarball 很好。如果有些测试失败，或者新解压缩的目录中存在任何其他奇怪的东西，您最好现在停止并找出问题所在。

  12. 您需要将 tgz 文件和 exe 文件上传到 creosote.python.org。此步骤所需的时间取决于您的网络带宽。使用 scp 将这两个文件从您的机器上传到 creosote。
  13. 在等待的同时，您可以开始修改网页，以包含公告。
    1. 在 python.org 网站的 CVS 树顶层，为 X.Y.Z 版本创建一个子目录。实际上，你可以复制之前补丁版本的子目录，但要确保删除 X.Y.Z/CVS 目录并执行 "cvs add X.Y.Z"，例如
      % cd .../pydotorg
% cp -r 2.2.2 2.2.3
% rm -rf 2.2.3/CVS
% cvs add 2.2.3
% cd 2.2.3
    2. 编辑文件内容：通常你可以全局替换 X.Ya(Z-1) 为 X.YaZ。但是，你需要考虑 "新增功能" 部分。
    3. 将 Misc/NEWS 文件复制到 python.org 的 X.Y.Z 目录下的 NEWS.txt 文件中；此文件包含自 Python 上一个版本发布以来对该 Python 版本的所有更改。
    4. 将之前创建的 .asc GPG 签名也复制到此目录中。
    5. 另外，更新 MD5 校验和。
    6. 通过执行 "make" 或 "make install" 预览网页（只要你为这个版本创建了新的目录！）。
    7. 同样，编辑 ../index.ht 文件，即 python.org 首页。在蓝色大公告块中，将新版本的段落移到最上面，并将 "Python X.YaZ 已发布" 这句话加粗。编辑内容，并在本地预览，但不要执行 "make install"！
  14. 现在我们正在等待 scp 到 creosote 完成。Da de da, da de dum, hmm, hmm, dum de dum。
  15. 完成之后，你需要转到 creosote.python.org 并将所有文件移到那里。我们的策略是每个 Python 版本都有自己的目录，但每个目录可能包含多个版本。我们保留所有旧版本，并在发布新版本时将它们移到 "prev" 子目录中。

    所以，有一个名为 "2.2" 的目录，其中包含 Python-2.2a2.exe 和 Python-2.2a2.tgz，以及一个 "prev" 子目录，其中包含 Python-2.2a1.exe 和 Python-2.2a1.tgz。

    所以……

    1. 在 creosote 上，cd 到 ~ftp/pub/python/X.Y，如果必要就创建它。
    2. 将之前的版本文件移到名为 "prev" 的目录中，如果必要就创建该目录（确保该目录有 g+ws 权限）。如果这是新 Python 版本的第一个 alpha 版本，请跳过此步骤。
    3. 将 .tgz 文件和 .exe 文件移到此目录中。确保它们对全世界可读。它们也应该对组可写，并且由 webmaster 拥有。
    4. 对文件进行 md5sum，并确保它们完整上传。
  16. 如果需要，编辑 X.Y/bugs.ht 文件。最好获得 BDFL 的意见来完成此步骤。
  17. 向上转到父目录（即网页层次结构的根目录），并执行 "make install"。你的版本现在正式上线了！
  18. 现在是为邮件列表撰写公告的时候了。这是模糊的部分，因为没有太多东西可以自动化。你可以使用 Guido 之前发布的公告作为模板，但请编辑内容！

    公告准备就绪后，将其发送到以下地址：

    python-list@python.org
python-announce@python.org
python-dev@python.org
  19. 在 SourceForge 上发布一个关于该版本的新闻条目。在项目的 "菜单栏" 中，选择 "新闻" 链接；进入新闻后，选择 "提交" 链接。在主题框中输入一个合适的主题（例如 "Python 2.2c1 发布" :-)，在详细信息框中添加一些文本（至少包括 www.python.org 上的发布 URL 和你对该版本感到满意的信息），然后单击 SUBMIT 按钮。

    可以随意删除任何旧新闻条目。

现在是进行一些清理的时候了。这些步骤非常重要！

  1. 编辑 Include/patchlevel.h 文件，使 PY_VERSION 字符串显示类似 "X.YaZ+" 的内容。注意尾部的 '+' 表示主干将继续进行开发。例如，这行代码应该看起来像
    #define PY_VERSION              "2.1.2+"

    确保其他 PY_ 版本宏包含正确的值。提交此更改。

  2. 对于额外谨慎的人来说，可以对版本进行完全干净的测试。这包括从 www.python.org 下载 tarball。
  3. 确保 md5 校验和匹配。然后解压缩 tarball，并进行干净的 make test。
    % make distclean
% ./configure
% make test

    确保回归测试套件通过。如果没有通过，说明你 somewhere 弄错了！

步骤 5 …

验证！这可以与步骤 4 交织进行。假设你是用户：从 python.org 下载文件，并从中构建 Python。这一步很容易被忽视，而且我们多次遇到过无用的发布文件。有一次，通用服务器问题导致所有文件神秘地损坏；有一次，源代码 tarball 构建错误；不止一次，SF 上的文件上传过程截断了文件；等等。

下一步？

欢呼吧。喝酒吧。尽情欢闹吧。像这样写一个 PEP。或者像 Guido 一样休个假。

你刚刚发布了一个 Python 版本！

实际上，还有一个步骤。你应该将该分支的所有权转让给 Jack Jansen。这意味着他现在将负责对该分支进行提交。他将使用它来构建 MacOS 版本。他可能会向你发送有关 Mac 版本的信息，这些信息应该合并到 www.python.org 上的信息页面中。完成之后，他会给该分支打上类似 "rX.YaZ-mac" 的标签。他还将负责将任何与 Mac 相关的更改合并回主干。

最终发布说明

任何主要版本的最终版本，例如 Python 2.2 正式版，都有特殊要求，特别是因为它将是寿命最长的版本之一（例如，测试版不会持续超过几周，但正式版本可以持续数年！）。

出于这个原因，我们希望在三个主要版本之间进行更高的协调：Windows、Mac 和源代码。Windows 和源代码版本受益于各自发布机器的紧密 proximity。但 Mac 发布机器，Jack Jansen，距离 6 个小时。因此，对于正式版本，我们向发布流程中添加了这一额外步骤。

  1. 在 Jack 批准之前，或在我们失去耐心之前 <wink>，停止发布正式版本。

当发布新的 bug 修复版本时，python.org 网站也需要进行一些调整。

  1. 文档应该安装在 doc/<version>/。
  2. 从 doc/<previous-minor-release>/index.ht 添加一个链接到新版本的文档。
  3. 所有旧的 doc/<old-release>/index.ht 文件都应该更新为指向新版本的文档。
  4. /robots.txt 应该修改为阻止搜索引擎抓取旧版本文档。

Windows 说明

Windows 有一个 GUI 安装程序，各种版本的 Windows 都有 "特殊限制"，Windows 安装程序还打包了预编译的 "外部" 二进制文件（Tcl/Tk、expat 等）。因此，Windows 测试很繁琐，但非常必要。

与上传安装程序同时，Thomas 从安装程序中安装两次 Python：一次安装到安装程序建议的默认目录中，另一次安装到目录名称中包含空格的目录中。对于每次安装，他都会从 DOS 框中运行完整的回归测试套件，并且使用和不使用 -0 两种方式。

他还尝试了 "开始" -> "菜单" -> "Python 组" 下创建的 **所有** 快捷方式。使用 IDLE 这种方式时，你需要验证 "帮助" -> "Python 文档" 是否有效。使用 pydoc 这种方式（"模块文档" 开始菜单条目）时，确保 "启动浏览器" 按钮有效，并确保你可以搜索随机模块（Thomas 使用 "random" <wink>），然后确保 "转到选中" 按钮有效。

令人惊讶的是，这里有多少东西可能出错——更令人惊讶的是，最后时刻的 checkin 有多少次会破坏其中的一项。如果你是 "Windows 极客"，请记住，你可能是唯一一个在 Windows 上定期进行测试的人，而 Windows 简直就是一团糟。

在至少一种版本的 Win9x 和一种版本的 NT/2000/XP 上重复上述所有操作。在 NT/2000/XP 上，尝试使用管理员帐户和普通用户帐户（不是高级用户帐户）。

关于上面的步骤 5（验证发布媒体），由于 Thomas 通常在发布文件准备好下载时就已经对上传的安装程序进行了许多 Windows 测试，因此他通常在步骤 5 中不做任何事情，除了对下载的文件和上传的文件进行完整的字节比较（如果使用 Windows shell，则使用 "fc /b"）。

来源：https://github.com/python/peps/blob/main/peps/pep-0102.rst

最后修改时间：2023-09-09 17:39:29 GMT