如何向公众发布 LLVM

简介

本文档包含有关成功向公众发布 LLVM（包括子项目：例如，clang 和 compiler-rt）的信息。发布管理器有责任确保发布高质量的 LLVM 版本。

如果您正在寻找有关如何测试候选版本和创建二进制软件包的文档，请参阅如何验证新版本。

发布时间表

LLVM 按照基于时间的计划发布——主要版本大约每 6 个月发布一次。在主要版本之间可能会有补丁版本。发布管理器将根据社区的反馈确定是否以及何时发布补丁版本。通常，如果稳定分支中有大量错误修复或发现了影响大量用户的关键错误，则应发布补丁版本。

除非另有说明，补丁版本的发布程序将与主要版本相同。

年度发布计划

以下是 LLVM 的年度发布计划。这仅供参考，发布管理器无需完全遵循。版本应在周二标记。

发布版本	大约日期
发布分支：偶数版本	一月份的第 4 个星期二
发布分支：奇数版本	七月份的第 4 个星期二
X.1.0-rc1	分支后 3 天。
X.1.0-rc2	分支后 2 周。
X.1.0-rc3	分支后 4 周
X.1.0-final	分支后 6 周
X.1.1	分支后 8 周
X.1.2	分支后 10 周
X.1.3	分支后 12 周
X.1.4	分支后 14 周
X.1.5	分支后 16 周
X.1.6（如有必要）	分支后 18 周

发布流程摘要

• 向 LLVM 社区宣布发布时间表并更新网站。在 -rc1 版本发布前至少 3 周执行此操作。

• 创建发布分支并开始发布流程。

• 发送第一个测试轮次的候选发布版本源代码。测试持续 6 周。在第一轮测试期间，应修复发现的任何回归。补丁从主线合并到发布分支。此外，所有功能都需要在此期间完成。在第一轮测试结束时未完成的任何功能都将被删除或禁用。

• 生成并发送第二个候选发布版本源代码。只有在此测试阶段发现的关键错误才会被修复。任何由合并补丁引入的错误都将被修复。如果是这样，则需要进行第三轮测试。

• 更新发布说明。

• 最后，发布！

• 向 LLVM 社区宣布错误修复发布时间表并更新网站。

• 每两周进行一次错误修复版本发布，直到 X.1.5 或 X.1.6（如有必要）。

发布流程

发布管理任务

本节介绍开始发布过程所需完成的一些管理任务。具体来说，它包括

• 更新版本号，

• 创建发布分支，以及

• 标记候选发布版本，以便发布团队开始测试。

创建发布分支

使用以下步骤分支 Git 主干

1. 提醒开发人员发布分支即将进行，并避免提交可能破坏构建的补丁。例如，新功能、正在进行中的工作的大型补丁、类型系统的彻底修改、令人兴奋的新 TableGen 功能等。

2. 通过检查夜间测试器和构建机器人的结果，验证当前的 git 主干是否处于良好状态。

3. 将主干中的版本提升到 N.0.0git，并使用 llvmorg-N-init 标记提交。如果 X 是要发布的版本，则 N 是 X + 1。

$ git tag -sa llvmorg-N-init

1. 清除主干中的发布说明。

2. 从版本提升之前的最后一个已知良好修订版本创建发布分支。分支的名称是 release/X.x，其中 X 是主版本号，x 只是字母 x。

3. 在新创建的发布分支上，立即将版本提升到 X.1.0git（其中 X 是分支的主版本。）

4. 所有标签和分支都需要在 llvm/llvm-project 和 llvm/llvm-test-suite 仓库中创建。

更新 LLVM 版本

创建 LLVM 发布分支后，使用 llvm/utils/release/bump-version.py 中的脚本更新发布分支的版本。

标记 LLVM 候选发布版本

标记候选发布版本

$ git tag -sa llvmorg-X.Y.Z-rcN

预先打包的源代码 tarball 将通过 GitHub 上的“Release Sources”工作流程自动生成。此工作流程将创建一个包含所有发布 tarball 和工件证明的工件。发布管理器应下载该工件，验证 tarball，对其进行签名，然后将其上传到发布页面。

$ unzip artifact.zip
$ gh auth login
$ for f in *.xz; do gh attestation verify --owner llvm $f && gpg -b $f; done

Tarball、发布二进制文件或任何其他发布工件必须上传到 GitHub。这可以使用 utils/release 中的 github-upload-release.py 脚本完成。

$ github-upload-release.py upload --token <github-token> --release X.Y.Z-rcN --files <release_files>

构建二进制发行版

创建二进制发行版需要按照此处的说明进行操作。

该过程将执行 Release+Asserts 和 Release 构建，但仅打包 Release 构建以进行上传。您应该使用 Release+Asserts 系统根目录，通常在 final/Phase3/Release+Asserts/llvmCore-3.8.1-RCn.install/ 下，进行测试套件和运行时基准测试，以确保没有严重的错误通过。对于编译时基准测试，请使用 Release 版本。

您需要的工具的最低版本在此处

发布资格标准

没有官方的发布资格标准。发布是否准备就绪由发布管理器决定。发布管理器在确定是否发布版本时，应注意社区测试的结果、未解决的错误数量以及回归数量。

社区重视基于时间的发布，因此除非存在关键问题，否则不应将发布延迟太久。在大多数情况下，唯一足以阻止发布的关键错误是从先前版本的主要回归。

官方测试

社区中的一些开发人员专门抽出时间来验证候选发布版本，并自愿成为每个架构的官方发布测试人员。

这些人将负责测试、生成和上传官方二进制文件到服务器，并且将是发布继续进行的必要最低限度测试。

这显然不会涵盖所有操作系统和发行版，因此额外的社区验证非常重要。但是，如果在发布版本之前没有收到社区的意见，则所有报告的错误都将进入下一个稳定版本。

官方发布管理器是

• 偶数版本：Tom Stellard (tstellar@redhat.com)

• 奇数版本：Tobias Hieta (tobias@hieta.se)

官方发布测试人员是从社区中自愿选出的，并且持续验证并发布其目标/操作系统的二进制文件。要联系他们，您应该在Discourse 论坛（项目基础设施 - 发布测试人员）上发帖。

官方测试人员列表在 LLVM 仓库的 RELEASE_TESTERS.TXT 文件中。

社区测试

一旦所有测试完成并且提交了相应的错误，候选发布版本的 tarball 将被放在网站上，并通知 LLVM 社区。

我们要求所有 LLVM 开发人员通过以下任何方式测试发布版本

1. 下载 llvm-X.Y、llvm-test-X.Y 和适当的 clang 二进制文件。构建 LLVM。运行 make check 和完整的 LLVM 测试套件 (make TEST=nightly report)。

2. 下载 llvm-X.Y、llvm-test-X.Y 和 clang 源代码。编译所有内容。运行 make check 和完整的 LLVM 测试套件 (make TEST=nightly report)。

3. 下载 llvm-X.Y、llvm-test-X.Y 和适当的 clang 二进制文件。使用它为您的平台构建完整的程序（例如 Chromium、Firefox、Apache）。

4. 下载 llvm-X.Y、llvm-test-X.Y 和适当的 clang 二进制文件。使用它构建您自己的程序，并检查一致性和性能回归。

5. 如果您的平台与官方支持的平台不同，请运行发布流程，并且仅当官方发布测试人员未报告该架构的错误时才报告错误。

我们还要求 OS 发行版管理器使用每个版本的第一个候选版本测试其软件包，并在 GitHub 中报告任何新的错误。如果该错误可以使用未打补丁的上游候选发布版本重现（而不是发行版自己的构建），则优先级应为发布阻止程序。

在第一轮测试期间，所有回归都必须在标记第二个候选发布版本之前修复。

在后续阶段，测试仅是为了确保先前合并的错误修复没有产生新的主要问题。这不是解决其他无关错误的时候！ 如果没有合并补丁，则确定发布版本已准备就绪，发布管理器可以进入下一阶段。

报告回归

在测试期间发现的每个回归（根据上述标准），都应在 GitHub 中填写错误，并添加到发布里程碑。

如果无法重现错误，或停止成为阻止程序，则应将其从里程碑中删除。调试可以继续，但在主干上进行。

反向移植请求

有关请求反向移植到稳定分支的说明，请参见此处。

发布版本的错误报告分类

本节介绍如何对错误报告进行分类

1. 搜索具有发布里程碑但未添加到“发布状态”github 项目的错误

   https://github.com/llvm/llvm-project/issues?q=is%3Aissue+milestone%3A%22LLVM+14.0.5+Release%22+no%3Aproject+

   将此查询中的 14.0.5 替换为目标发布里程碑的版本。

   将这些错误添加到“发布状态”项目。

2. 导航到发布状态项目以查看正在考虑用于发布的错误列表。

3. 查看每个错误，首先检查它是否已在主分支中修复。如果已修复，请将其状态更新为“需要拉取请求”，并使用 /cherry-pick 或 /branch 注释为修复创建拉取请求（如果尚未完成）。

4. 如果错误已修复并且已创建用于反向移植的拉取请求，则将其状态更新为“需要审核”，并通知有知识的审核人员。通常，您会希望通知在 Phabricator 中批准补丁的人，但您可以自行判断谁是好的审核人员。确定审核人员后，将问题分配给他们，并在评论中提及他们（即 @username），并询问他们补丁是否可以安全地反向移植。您还应该自己审核错误，以确保其满足提交到发布分支的要求。

5. 审核错误后，添加 release:reviewed 标签，并将问题的状态更新为“需要合并”。检查与问题关联的拉取请求。如果所有测试都通过，则可以合并拉取请求。如果未通过，则在问题上添加评论，要求某人查看失败情况。

6. 合并拉取请求后，使用脚本 llvm/utils/git/sync-release-repo.sh 将其推送到官方发布分支。

   然后向问题添加评论，说明修复已合并以及来自发布分支的 git 哈希值。向问题添加 release:merged 标签并关闭它。

发布补丁规则

以下是有关修补发布分支的规则

1. 应用于发布分支的补丁只能由发布管理器、官方发布测试人员或维护人员在获得发布管理器的批准后应用。

2. 鼓励但不要求发布管理器在批准补丁之前获得维护人员的批准。如果没有可联系的维护人员，则发布管理器可以向补丁审核人员或该领域活跃的其他开发人员寻求批准。

3. 在 RC1 之前，补丁应仅限于错误修复、重要的优化改进或在创建分支之前开始的功能的完成。与所有阶段一样，发布管理器和维护人员可以拒绝被认为侵入性太强的补丁。

4. 在 RC2 之前，补丁应仅限于错误修复或确定非常安全的后端特定改进。

5. 在 RC3/最终主要版本之前，补丁应仅限于关键错误或回归。

6. 错误修复版本，补丁应仅限于错误修复或非常安全和关键的性能改进。补丁必须保持与 X.1.0 版本的 API 和 ABI 兼容性。

发布最终任务

发布过程的最后阶段包括标记“最终”发布分支、更新引用发布的文档以及更新演示页面。

更新文档

查看发布分支中的文档，并确保其是最新的。“发布说明”必须更新以反映新功能、错误修复、新的已知问题以及受支持平台列表中的更改。“入门指南”应更新以反映 Subversion 中提供的新发布版本号标签以及基本系统要求的更改。

标记 LLVM 最终版本

标记最终发布版本的源代码

$ git tag -sa llvmorg-X.Y.Z
$ git push https://github.com/llvm/llvm-project.git llvmorg-X.Y.Z

更新 LLVM 网站

网站必须在发布公告发送之前更新。以下是要执行的操作

1. 从 GitHub 检出 www-releases 模块。

2. 在 releases 目录中创建一个新的子目录 X.Y.Z。

3. 将 llvm/docs 和 LICENSE.txt 文件复制并提交到这个新目录中。

4. 使用 GitHub 上发布二进制文件的链接更新 releases/download.html 文件。

5. 使用新版本更新 releases/index.html 并链接到发布文档。

6. 在您将更改推送到 www-releases 仓库后，具有管理员权限的人员必须登录到 prereleases-origin.llvm.org 并手动将新更改拉取到 /data/www-releases/ 中。这是网站提供服务的位置。

7. 最后检出 llvm-www 仓库并更新主页（index.html 和侧边栏）以指向新版本和发布公告。

发布公告

一旦所有发布任务完成，在公告类别中创建一个新帖子。对于 X.1.0 版本，请确保在帖子中包含发布说明的链接。对于 X.1.1+ 版本，使用此命令生成变更日志并将其添加到帖子中。

$ git log --format="- %aN: [%s (%h)](https://github.com/llvm/llvm-project/commit/%H)" llvmorg-X.1.N-1..llvmorg-X.1.N

发布公告后，在 llvm 主页（来自 llvm-www 仓库）的“发布邮件”部分中添加指向公告的链接。