佳佳的博客

Appearance

JEP 369: Migrate to GitHub | 迁移到 GitHub ​

原文

JEP 369: Migrate to GitHub

摘要 ​

将 OpenJDK 社区的 Git 仓库托管在 GitHub 上。与 JEP 357（从 Mercurial 迁移到 Git） 协同工作，这将把所有单仓库 OpenJDK 项目迁移到 GitHub，包括 JDK 功能发布 和 11 及更高版本的 JDK 更新发布。

目标 ​

  • 在 https://github.com/openjdk/ 托管所有 OpenJDK Git 仓库。
  • 在每次推送之前运行预提交检查（jcheck）。
  • 集成现有的 OpenJDK 服务。
  • 启用与 GitHub 的多种交互方式。
  • 确保支持结构上类似于现有基于电子邮件和 webrev 的工作流。
  • 保留和归档所有元数据。
  • 确保 OpenJDK 社区始终能够迁移到不同的源代码托管提供商。
  • 不要求开发人员安装 OpenJDK 特定工具即可进行贡献。
  • 不改变 OpenJDK 的 章程。
  • 不改变 OpenJDK 的 人口普查。

非目标 ​

不改变 OpenJDK 社区的 问题跟踪器、wiki 或任何其他现有基础设施。

成功指标 ​

  • 显著加快克隆和拉取时间
  • 提高仓库的可用性（正常运行时间）
  • 可以通过 OpenJDK 邮件列表与 GitHub 上的仓库进行交互
  • 可以通过命令行工具与 GitHub 上的仓库进行交互
  • 可以通过 Web 浏览器与 GitHub 上的仓库进行交互

动机 ​

本 JEP 的动机分为两部分。首先，我们阐述为什么 OpenJDK 社区会受益于使用外部源代码托管提供商，然后解释为什么 GitHub 是目前最佳的提供商选择。

为什么选择外部源代码托管提供商？ ​

外部源代码托管提供商是一种源代码仓库服务，不由 OpenJDK 社区的贡献者实施和管理。外部提供商的示例包括 BitBucket、GitLab、Phacility、SourceForge 和 GitHub。

OpenJDK 社区使用外部源代码托管提供商主要有三个原因：

  • 性能。许多（如果不是全部）提供商都具备出色的性能，不仅在网络性能上表现优异，而且在可用性（即正常运行时间）方面也表现出色。对于 OpenJDK 社区而言，这将导致克隆和拉取时间显著加快，以及更高可用性的源代码仓库。

  • API。将 OpenJDK 仓库托管在源代码托管平台上的技术原因之一是能够获得 Web API 的访问权限，这些 API 使程序能够与平台上的开发人员进行交互。虽然今天通过电子邮件与开发人员交互并非不可能实现，但与使用结构化 API 相比，实现解释电子邮件中自由格式文本的程序要困难得多。允许程序参与审查过程可以实现强大的自动化；有关几个示例，请参阅 描述 部分。

  • 扩大的社区。 最大的提供商还将为 OpenJDK 社区提供机会，以利用现有的大型开发人员和潜在贡献者社区。如果开发人员已经在某个提供商上拥有帐户，那么他们只需进行少数额外步骤即可为 OpenJDK 做出贡献。在更大的 Java 社区中，几乎所有开源项目都托管在外部提供商上，包括多个 OpenJDK 发行版。如果 OpenJDK 仓库也托管在同一提供商上，这将促进更紧密的合作。

使用外部提供商的一个缺点和风险是，提供商可能会关闭，或者由于某些其他原因导致源代码和相关材料无法访问。有关如何处理和减轻此风险，请参阅 风险和假设 部分。

另一个需要考虑的因素是迁移到外部提供商对现有贡献者工作流程的影响。请参阅 描述 部分，了解如何借助源代码托管平台的 API 支持多种工作流程，包括如何保留 OpenJDK 社区现有的几乎所有工作流程。

为什么选择 GitHub？ ​

选择 GitHub 的动机在于它完美符合选择外部提供商的三个主要原因。GitHub 的性能与其他提供商相当或更优，它是全球最大的源代码托管服务（截至 2020 年 5 月拥有 5000 万用户），并且拥有最广泛的 API 之一。

GitHub 的广泛 API 使得许多工具都支持 GitHub，包括文本编辑器、集成开发环境（IDE）、命令行工具和图形桌面客户端。以下文本编辑器支持 GitHub（即开发人员可以直接在文本编辑器中创建、审查和评论拉取请求）：

以下集成开发环境（IDE）支持在 GitHub 上与拉取请求进行交互：

还有一款命令行客户端 hub（开源）和几个图形桌面客户端，例如 SourceTree、Tower 和 GitHub Desktop（开源）。

还有许多其他出色的源代码托管提供商。请参阅 风险和假设 部分，了解为什么这很重要以及它如何使我们能够推荐 GitHub。

描述 ​

迁移到外部源代码托管提供商的有趣之处 不在于 将实际仓库上传到服务；鉴于 JEP 357（从 Mercurial 迁移到 Git） 的工作，这很简单。

有趣的是迁移到外部提供商将如何影响 OpenJDK 贡献者的工作流程。

目前，OpenJDK 贡献者通过 邮件列表 进行合作，他们将更改推送到 Mercurial 仓库，通过 jdk/submit 服务测试更改，并通过 JDK Bug System（JBS）提交错误报告。贡献者还可以使用几种命令行界面（CLI）工具，主要是 jcheck、webrev 和 defpath。这是一个许多经验丰富的贡献者喜欢并认为富有成效的工作流程。因此，如果我们迁移到外部提供商，尽可能保留这一工作流程至关重要。

GitHub 和其他流行的托管提供商上的工作流程采用了 拉取请求（PR）的概念，从高层次上看，这与 OpenJDK 贡献者今天使用的请求审查（RFR）电子邮件类似。GitHub 上的贡献者从特定仓库的源分支向目标分支创建 PR（源分支和目标分支不必位于同一仓库中）。然后，其他贡献者会审查 PR，并根据审查者的反馈在源分支上进行额外的提交。一旦审查者对更改感到满意，PR 就会被合并到目标分支中。

本 JEP 提议支持多种工作流程，使用 Project Skara 中开发的工具。贡献者可以选择最适合他们的工作流程：

  • 基于 CLI + 邮件列表（类似于当前的工作流程）
  • 基于 Web 浏览器（通过 GitHub 网站）
  • 基于文本编辑器和 IDE（通过文本编辑器和 IDE 中的插件和 GitHub 支持）
  • 基于 CLI（通过自定义 CLI 工具）

当然，也可以混合搭配不同的工作流程。对于像 OpenJDK 这样庞大且多样化的开源社区来说，各个贡献者工作流程的共同点就是它们各不相同。在描述各种工具和服务之前，我们先以一个新变更合并的工作流程为例进行说明。（有关更专门的任务（如仓库间同步或添加标签）的工作流程将在本 JEP 的未来修订版本中讨论。）

工作流程 ​

这四个工作流程的共同之处在于，每个变更都以拉取请求（PR）开始。PR 可以通过多种方式创建——从 CLI、Web 浏览器、文本编辑器或 IDE。但是，创建 PR 需要在 GitHub 上拥有一个帐户。对于不希望在 GitHub 上创建帐户的贡献者，我们仍将继续接受发送到 OpenJDK邮件列表 的补丁。但是，这些补丁需要有一个拥有 GitHub 帐户的贡献者来创建 PR，这与当前许多贡献者如何帮助新手创建并上传 webrevs 到 cr 类似。

在创建 PR 之后，PR 中的提交将被 jcheck 提交分析工具分析，该工具作为服务器端程序（所谓的“机器人”）运行。jcheck 机器人使用外部提供商的 API 将潜在问题作为评论或错误呈现，具体取决于提供商 API 的功能。在 GitHub 上，jcheck 机器人特别使用 Checks API 来生成有用的错误消息。jcheck 机器人可通过仓库中的 .jcheck/config 配置文件进行配置。如果已配置，其中一个检查将确保所提出的更改在 JBS 中有一个对应的问题。在这种情况下，机器人将确保 PR 的标题与 JBS 问题的标题相对应，类似于 RFR 电子邮件的标题。如果 PR 的标题包含 JBS 问题，则 jbs 机器人会在相应的 JBS 问题中为 PR 添加一个 链接。

PR 一旦通过 jcheck 检查，就会被贴上 "rfr" 标签。这向潜在的评审者表明，该 PR 现已准备好进行评审。（评审者没有必要参与甚至未通过 jcheck 检查的变更。）此时，PR 还会根据 PR 中提交所更改的源代码区域自动贴上标签。例如，对 jdk 仓库的 master 分支进行 PR，其中在 make 目录和 src/hotspot 目录中都有更改，那么该 PR 将获得 build-dev 和 hotspot-dev 标签。此时，会自动向 build-dev@openjdk.java.net 和 hotspot-dev@openjdk.java.net 邮件列表以及 PR 作者指定的任何其他列表发送自动生成的 RFR 电子邮件。RFR 电子邮件包含 PR 的标题和正文、PR 中提交的自动生成的摘要，以及自动生成的 webrevs 链接。

现在，评审者可以使用多种工作流程讨论 PR 中的变更：

  • 通过回复发送到邮件列表的 RFR 电子邮件进行讨论，此时回复的内容将被复制到 GitHub 上的 PR 中（无需 GitHub 帐户）；
  • 通过 Web 浏览器使用 https://github.com/ 上的评审工具进行讨论；
  • 使用与 GitHub 集成的各种文本编辑器和 IDE 中的评审工具进行讨论；
  • 使用与 GitHub 集成的图形桌面应用程序进行讨论；
  • 使用 Skara CLI 工具进行讨论。

在任何一种工作流程中发表的任何评论都会反映在所有工作流程中。一位评审者可以通过邮件列表添加评论，另一位可以通过 Web 浏览器添加评论，第三位可以通过命令行添加评论，并且他们都能看到彼此的评论。

如果 PR 作者根据评审者的反馈向源分支推送了额外的提交，那么一个机器人会向 RFR 电子邮件发送回复，包括新提交的自动摘要以及自动生成的增量和完整 webrevs。

当评审者对变更感到满意时，他们会将 PR 标记为已评审。这可以通过以下方式完成：

  • 使用 Web 浏览器和 https://github.com/，
  • 使用命令行中的 git pr approve，
  • 使用与 GitHub 集成的文本编辑器和 / 或 IDE，
  • 使用与 GitHub 集成的图形桌面工具。

一旦所有评审者都满意，PR 的作者就可以最终集成 PR。他们通过在评论中添加确切内容 /integrate 来做到这一点，之后会发生几件事情：

  1. 一个机器人将所有提交压缩（合并）成一个提交。
  2. 如有必要，机器人会将压缩后的提交基于目标分支（通常是 master）进行变基。
  3. 机器人会为最终提交构建提交信息，其中包括：
    • PR 的标题作为提交信息的标题，
    • 基于以 /summary 开头的 PR 评论的正文，
    • 在 Reviewed-by: 行中添加所有评审者的 OpenJDK 用户名，
    • 在 Co-authored-by: 行中添加所有共同作者。
  4. 机器人将生成的提交推送到目标分支（通常是 master）。

在实际集成 PR 之前，作者可以预览发出 /integrate 命令的结果，包括提交信息。

如果 PR 的作者不是 OpenJDK 的 提交者，那么在作者在评论中发出 /integrate 命令后，会添加 sponsor 标签。此时，一个 OpenJDK 的 提交者 必须在新评论中输入 /sponsor 命令来集成 PR。

权限和角色 ​

如 前文所述，我们并不打算改变 OpenJDK 的 人口普查，也不会将 OpenJDK 贡献者的角色和权限建模在外部源代码托管平台上。相反，服务器端工具（“机器人”）维护了一个 OpenJDK 贡献者 GitHub 用户 ID（而非不稳定的用户名）到 OpenJDK 用户名的映射。这样一来，机器人就可以检查，例如，一个 PR 的作者是否是 OpenJDK 的 作者，或者一个 PR 的评审者是否是 OpenJDK 的 评审者。此模型与外部提供商无关。这也意味着无需在外部提供商上重复 OpenJDK 的 人口普查 数据。

工具 ​

Skara 项目的贡献者已开发了多种支持此 JEP 的工具，包括在贡献者计算机上本地运行的 CLI 工具和在提供商服务器上运行的服务器端工具（“机器人”）。CLI 工具主要用于帮助希望从命令行与外部提供商交互的贡献者。这些工具包括：

  • git-fork：在外部提供商上 fork 一个项目并克隆它
  • git-pr：更新、批准、获取、显示等 PR
  • git-sync：从上游仓库同步分支
  • git-publish：将本地分支发布到远程仓库
  • git-info：从提交消息中提取 OpenJDK 特定信息
  • git-token：与 Git 凭据管理器交互以处理令牌
  • git-proxy：将所有 Git 命令的网络流量通过 HTTP(S) 代理
  • git-skara：了解并更新 Skara CLI 工具

以下 CLI 工具已提供，以支持 JEP 357（从 Mercurial 迁移到 Git）：

  • git-jcheck：在本地运行 jcheck
  • git-webrev：创建 webrev
  • git-defpath：设置推送和拉取路径
  • git-translate：在 hg 和 git 哈希值之间进行转换

辅助贡献者的机器人包括：

  • pr：检查、标记和集成拉取请求
  • ml-bridge：在邮件列表和源代码托管服务之间桥接评论
  • notify：在推送后向邮件列表发送通知
  • archiver：在 Git 仓库中以 JSON 格式存档所有 PR 元数据
  • forwarder：将推送的提交转发到其他仓库（例如，沙盒）
  • jbs：更新 JBS（类似于现有的“hgupdater”服务）
  • submit：作为机器人实现的测试服务示例

服务 ​

除了机器人之外，还有两项服务可帮助贡献者和评审者：

  • OCA 服务：减轻评审者检查贡献者是否已签署 Oracle 贡献者协议 的负担。

  • 测试服务 是 jdk/submit 仓库的通用版本。它允许贡献者在 PR 评论中发出 /test 请求，一个或多个测试服务可以对此进行响应。测试服务的简单示例已经以提交机器人的形式提供。

备选方案 ​

  • 继续使用 Mercurial 和现有的 OpenJDK 工作流程。（对于像 JDK 这样的大型存储库，我们不认为使用 hg-git 或类似工具来保留服务器端 Git 主存储库的客户端 Mercurial 版本是可行的。）

  • 使用 GitLab EE 作为外部源代码托管提供商。

  • 使用 BitBucket 作为外部源代码托管提供商。

测试 ​

  • 几乎所有工作流场景都已在 Skara 项目中作为集成测试实现。

  • Skara 项目已经长时间使用提议的工作流来处理自己的代码。

  • 其他几个 OpenJDK 项目已基于评估目的将其存储库迁移到 GitHub：OpenJFX、Loom、Mobile、OpenJMC、Panama、Metropolis、Valhalla、Amber、Tsan、ZGC、Lanai 以及一些 Code Tools 项目。这些项目已经对工具、机器人和服务进行了实际测试，以确保进一步的项目迁移能够顺利进行，减少阻力。

风险与假设 ​

切换到外部源代码托管提供商的主要风险是 OpenJDK 社区可能会变得依赖该提供商。由于 Git 的分布式特性，版本控制数据本身将始终独立于提供商。然而，存在一种风险，即诸如代码审查注释之类的元数据可能会被锁定到特定的提供商中。此外，还存在一种风险，即工具和工作流程可能会变得依赖于特定的提供商，从而由于工具中的假设而使得更换提供商变得不可能。

缓解这些风险一直是 Skara 项目的主要关注点。以下设计决策确保了关键元数据不会被锁定到任何特定的提供商中：

  • 拉取请求中的所有讨论都将复制到相应的 OpenJDK邮件列表 中。
  • 拉取请求中的所有讨论都将以两种格式存档：mbox（供人类阅读）和 JSON（供软件消费）。
  • 将推送通知发送到相应的 *-changes@openjdk.java.net 邮件列表，从而避免了对提供商 RSS 源的依赖。
  • 使用 OpenJDKCensus 进行用户组织和权限级别管理，从而避免了对提供商用户组织工具的依赖。
  • 域名 https://git.openjdk.java.net/ 将重定向到 OpenJDK 社区的当前源代码托管提供商。在 JBS 问题 和邮件列表消息中记录的源代码 URL 使用此域名，而不是当前提供商的域名。

为了防止 Skara 工具依赖于特定提供商的 API，从一开始就严格要求支持多个外部提供商。所有工具也必须与开源的 GitLab Community Edition（GitLab CE）一起工作。

依赖项 ​