Twisted 发布流程¶

本文档描述了 Twisted 的发布流程。虽然它仍然不完整，但我们已尽一切努力确保其准确性和最新性。

如果您想更改发布流程，请遵循正常的 Twisted 开发流程（贡献具有文档和单元测试的发布自动化软件，以证明其有效性）。

结果¶

在 Twisted 发布结束时，我们将拥有

发布在 PyPI Twisted 项目上的 Wheel 和 sdist 包。
更新的文档（API 和操作指南）在 Twisted Read The Docs 上，用于 stable 和 $RELEASE 版本。
发送到 Twisted 主邮件列表的发布公告邮件
一个 GitHub 发布，其中包含我们 Git 存储库中的相关标签

先决条件¶

要发布 Twisted，您需要

Twisted GitHub 存储库的提交权限。

依赖项¶

以下是发布流程中使用的移动部件和 Web 服务列表。对于日常操作，您不需要管理访问权限。如果出现问题，您应该了解它们并获得管理访问权限。

发布标签是通过 GitHub 发布 GUI 自动创建的。
PyPi 文件发布是在创建标签时通过 GitHub Actions 工作流完成的。任何 GitHub 中的 Twisted 贡献者都应该有权修改工作流。
docs.twistedmatrix.com 是一个 CNAME，您需要访问 Twisted DNS 服务器才能修改它。
文档通过 Read The Docs Twisted 项目发布。有一个自动化规则 <https://readthedocs.org/dashboard/twisted/rules/regex/1057/> 用于为每个匹配 ^twisted-\d+\.\d+\.\d+$ 的标签激活文档（候选发布除外）从 RTD 高级设置中，名为 stable 的分支被配置为默认分支。名为 stable 的分支还有一个“活动”文档版本。

版本号¶

Twisted 发布使用基于时间的编号方案，遵循 PEP440 约定。发布版本如 YY.MM.mm，其中 YY 是发布年份的后两位数字，MM 是发布月份，mm 是错误修复发布的编号。

有 3 种发布类型

当 YY.MM 更新时，进行主要发布。
当 mm 编号更新时，进行错误修复/补丁/小版本发布
候选发布，作为预发布，如 YY.MM.mmrc1

例如

2017 年 1 月的发布版本为 17.1.0
2017 年 11 月的发布版本为 17.11.0
如果 17.11.0 存在一些严重缺陷，则进行错误修复 17.11.1
17.1.0 的第一个候选发布版本为 17.1.0rc1，第二个为 17.1.0rc2

Twisted 的每个发布版本都包含整个项目。

在本文档中，我们将发布版本号称为 $RELEASE。$RELEASE 的示例包括 10.0.0、10.1.0、10.1.1 等。

我们将发布版本的前两个部分称为 $API，因为所有共享这些数字的发布版本在 API 上是相互兼容的。例如，对于 10.0.0，$API 为 10.0；对于 10.1.0 和 10.1.1，$API 为 10.1。

Incremental 会自动为您选择正确的版本号。请在运行它之后检索它。

概述¶

要发布 Twisted，我们

准备发布
发布一个或多个候选发布版本
发布最终发布版本

准备发布¶

使用发布阻碍 GitHub 问题搜索检查是否存在任何回归。
任何回归都应该在创建发布分支之前修复并合并到主干中。
选择一个版本号。对于主要发布，$RELEASE 将类似于 21.7.0。对于错误修复发布，$RELEASE 将类似于 21.7.1。
在 Trac 中创建一个名为“发布 $RELEASE”的工单，并将其分配给自己。
为发布创建一个分支。使用 release-$RELEASE-$GITHUB_ID 作为分支名称非常重要（4290 是 GitHub 问题 ID，21.7.0 是发布版本号），因为这被用作 CI 的提示
- git fetch origin
- git checkout origin/trunk
- git checkout -b release-21.7.0-4290

如何进行候选发布¶

本节描述了创建第一个候选发布版本所需的步骤和要求。

准备分支¶

检查主干分支（trunk）上的所有 CI 测试是否通过。主干分支上的失败测试应被视为发布阻碍。它们应该在单独的工单/PR 中修复。一旦主干分支恢复正常，发布就可以继续进行。
在您的 Git 存储库中，获取并检出新的发布分支。
运行 python -m incremental.update Twisted --rc
提交 Incremental 所做的更改。
运行 tox -e towncrier。
提交 towncrier 所做的更改 - 这会自动删除 newsfragment 文件。
如果需要，在 LICENSE、src/twisted/copyright.py 和 README.rst 中更新版权日期
将更改推送到 GitHub 并创建一个新的发布 PR。
GitHub PR 专用于最终发布，同一个 PR 用于发布候选版本和最终版本。
等待所有 PR 检查通过。
如果检查失败，请调查原因。如果只是测试不稳定，请重试运行。任何严重错误都应被视为发布阻碍，应在单独的工单/PR 中修复。避免在发布分支中进行非发布更改（即使是微小的更改）。
使用 GitHub 创建发布 UI 进行新的发布。
使用格式 twisted-VERSION 创建一个标签，该标签基于发布分支上的最新提交，确保版本包含 rc 后缀，例如 twisted-24.2.0rc1。
使用 Twisted VERSION 作为发布名称，例如 Twisted 24.2.0rc1。
将发布 NEWS 添加到 GitHub 发布页面。
确保选中“这是一个预发布”。
当新的标签被推送到存储库时，Github Actions 会将 dist 上传到 PyPI。
您可以通过 GitHub Action 检查自动上传的状态。
Read the Docs 钩子没有候选发布版本的版本。使用拉取请求发布的 Read the Docs。
文件在 PyPI 上发布后，将请求 PR 的审查，以便可以进行完整的审查和手动测试。
很可能通过电子邮件或 GitHub 收到一些关于发布说明最终内容的次要评论。在发布分支中进行这些更改是可以的。更新候选发布说明的文本是可以的，在最终 NEWS 文件中，候选发布版本将被删除并替换为最终版本。无需新的工单或单独的拉取请求。这些更改将在最终发布审查流程中进行审查。
在最终的公开版本发布并创建发布标签之前，发布分支将不会与主干保持同步。

发布公告¶

编写发布公告
在以下平台上发布候选版本：
- twisted-python 邮件列表，发送主题为“Twisted $RELEASE 预发布公告”的电子邮件
- IRC 的 #twisted-dev 频道，发送版本号或 pip 安装命令

候选版本公告可能提到自上次发布以来的重要更改，并请读者测试此候选版本。

以下是 $RELEASE 候选版本公告的示例

On behalf of the Twisted contributors I announce the release candidate of Twisted $RELEASE

Short summary of the release.
For example:
Python 3.5 is no longer a supported platform.
The minimum supported platform is Python 3.6.7.


The notable changes are:

* Mention the main new features.
* As well as important bug fixes
* Or deprecation/removals

The release and NEWS file is available for review at

   https://github.com/twisted/twisted/pull/PRID/files

Release candidate documentation is available at

   https://twisted--PRID.org.readthedocs.build/en/PRID/

Wheels for the release candidate are available on PyPI

   https://pypi.org/project/Twisted/$RELEASErc1

   python -m pip install Twisted==$RELEASErc1

Please test it and report any issues.
If nothing comes up in one week,
$RELEASE will be released based on the latest release candidate.

Many thanks to everyone who had a part in Twisted
the supporters of the Twisted Software Foundation,
the developers, and all the people testing and building great things with Twisted!

一般来说，在进行最终发布之前等待一周是一个不错的时长。

如何进行最终发布¶

准备分支¶

检出之前用于生成候选版本的发布分支
运行 python -m incremental.update Twisted --newversion $RELEASE
手动更新 NEWS 文件中的发布版本和日期。候选版本说明将从最终的 NEWS 文件中删除。手动将所有候选版本的发布说明移动到最终版本的说明中。
提交并推送。
提交最终审核的工单。
暂停，直到工单被审核并接受。
使用 GitHub 创建发布 UI 进行新的发布。
使用格式 twisted-VERSION 创建一个标签，该标签基于审核后发布分支上最新的提交。
使用 Twisted VERSION 作为发布的名称。
将发布 NEWS 添加到 GitHub 发布页面。
确保未选中“这是一个预发布”。
当新的标签被推送到仓库时，GitHub Actions 将将 dist 上传到 PyPI。PyPI 是 Twisted 包的唯一规范来源。
Read the Docs 钩子将为标签发布新版本的文档。

发布公告¶

编写发布公告，该公告应类似于候选版本公告，并包含更新的版本和发布日期。
发布公告
- 将公告的文本版本发送到：twisted@python.org
- 如果你愿意，也可以发布到 Twitter、TikTok、Instagram、Snapchat 等平台。
- #twisted IRC 消息

发布后¶

运行 python -m incremental.update Twisted --post 添加 post 版本号。
提交 post0 更新更改。
将主干更新到发布分支，解决任何可能的冲突。
无需再次请求审核。
将发布分支合并到主干（通过 GitHub PR UI），同时关闭发布工单。

安全发布¶

安全发布是指包含修复安全漏洞的版本，并附带安全公告。

遵循一般发布的所有步骤。还需要执行一些额外的步骤来传达安全问题。

这些发布在安全公告的 PR 合并后立即进行。

PR 贡献者和发布经理应进行沟通和协调发布。

任何阻止发布的步骤应由 PR 贡献者完成。发布经理的角色只是确保此流程得到遵循。

确保为该工单创建了GitHub 安全公告。
确保已请求 CVE，并且 CVE ID 和 GitHub Actions 安全公告 ID 包含在 newsfragment 中。
确保 PR 已获批准。
确保 GitHub 安全公告中提供了所有详细信息。
安全修复将在新版本的第一个候选版本中提供。因此，已修补的版本将类似于 YEAR.MONTH.0rc1。
使用 GitHub UI 合并 PR。
在主分支中提交后，创建一个新分支，并遵循一般候选版本流程。

PR 合并后，修复已公开，但尚未发布。尝试在安全 PR 合并后尽快进行候选版本发布。

如果可能，请尽量不要在工作周结束或周末进行安全发布。

候选版本修复¶

本节描述了在发布候选版本后发现严重缺陷或回归缺陷时应遵循的步骤。

如果在最终版本发布后发现缺陷，请查看下一节：“错误修复版本”。

暂停发布流程。
每个缺陷应分别创建工单。
应修复缺陷，并在主干中进行审核和合并。
在发布分支上，从主干中挑选合并修复的合并 git cherry-pick -m 1 TRUNK_MERGE_SHA。
遵循与任何候选版本相同的步骤，但无需创建新分支。使用相同的 python -m incremental.update Twisted –rc 命令来递增候选版本号。

不要删除已为发布推送的标签。使用递增的版本创建新的标签。

错误修复版本¶

有时会发生错误，有时这些错误是当前发布版本的回归。

由于资源不足，我们不会进行维护/补丁版本发布，包括安全问题。

我们只使用基于日历的版本方案进行正常发布。

我们欢迎更多志愿者加入发布工作。