如何向公众发布 LLVM

简介

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

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

发布时间线

LLVM 根据时间安排发布——主要版本大约每 6 个月发布一次。在主要版本之间，可能会发布点版本。发布经理将根据社区的反馈决定是否以及何时发布点版本。通常，如果稳定分支中存在大量错误修复或发现影响大量用户的严重错误，则应发布点版本。

除非另有说明，否则点版本将遵循与主要版本相同的程序。

年度发布计划

以下是 LLVM 的年度发布计划。这只是一个指南，发布经理不需要完全遵循它。版本应在星期二进行标记。

版本

大约日期

发布分支：偶数版本

1 月份的第四个星期二

发布分支：奇数版本

7 月份的第四个星期二

X.1.0-rc1

分支后 3 天。

X.1.0-rc2

分支后 2 周。

X.1.0-rc3

分支后 4 周

X.1.0-最终版

分支后 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

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

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

压缩包、发布二进制文件或任何其他发布工件必须上传到 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 版本。

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

发布资格标准

没有官方的发布资格标准。发布经理负责决定何时发布版本。在确定是否发布版本时，发布经理应关注社区测试的结果、未解决错误的数量以及回归的数量。

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

官方测试

社区中的一些开发人员已投入时间来验证候选版本，并自愿担任每个架构的官方发布测试人员。

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

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

官方发布经理是

官方发布测试人员来自社区的志愿者，他们始终如一地验证并为他们的目标/操作系统发布二进制文件。要联系他们，您应该在Discourse 论坛（项目基础设施 - 发布测试人员）上发帖。

官方测试人员列表位于LLVM存储库中的RELEASE_TESTERS.TXT文件中。

社区测试

一旦所有测试完成并提交了相应的错误，候选版本压缩包将被放置在网站上，并通知 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. 如果您的平台与官方支持的平台不同，请运行 发布流程，并且仅当官方发布测试人员未报告该架构的错误时，才报告错误。

我们还要求操作系统发行版发布管理者使用每个版本的第一个候选版本测试其软件包，并在 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. 错误修复版本补丁应仅限于错误修复或非常安全且重要的性能改进。补丁必须保持与先前主要版本的 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 存储库）的“发布电子邮件”部分添加指向该公告的链接。