JEP 369：迁移到 GitHub

概括

在GitHub上托管 OpenJDK 社区的 Git 存储库。与JEP 357（从 Mercurial 迁移到 Git）配合，这会将所有单存储库 OpenJDK 项目迁移到 GitHub，包括版本 11 及更高版本的JDK 功能版本和JDK 更新版本。

目标

• 将所有 OpenJDK Git 存储库托管在https://github.com/openjdk/。
• 每次推送之前运行预提交检查 ( jcheck )。
• 集成现有的 OpenJDK 服务。
• 启用与 GitHub 交互的多种方式。
• 确保支持结构上与现有电子邮件和基于 Webrev 的工作流程相似的工作流程。
• 保存并归档所有元数据。
• 确保 OpenJDK 社区始终可以转移到不同的源代码托管提供商。
• 不需要开发人员安装 OpenJDK 特定工具才能做出贡献。
• 不要更改 OpenJDK章程。
• 不要更改 OpenJDK Census。

非目标

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

成功指标

• 克隆和拉取时间显着加快
• 存储库的更好可用性（正常运行时间）
• 可以通过 OpenJDK 邮件列表与 GitHub 上的存储库进行交互
• 可以通过命令行工具与 GitHub 上的存储库进行交互
• 可以通过网络浏览器与 GitHub 上的存储库进行交互

动机

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

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

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

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

• 表现。许多（如果不是全部）提供商都具有出色的性能，不仅在网络性能方面，而且在可用性（即正常运行时间）方面也是如此。对于 OpenJDK 社区来说，这将显着加快克隆和拉取时间，并提供更高可用性的源代码存储库。

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

• _扩大的社区。_最大的提供商还将为 OpenJDK 社区提供进入大型现有开发人员社区和潜在贡献者的机会。如果开发人员已经在提供商上拥有帐户，则只需执行几个额外步骤即可为 OpenJDK 做出贡献。大型 Java 社区中的几乎所有开源项目都托管在外部提供商上，包括多个 OpenJDK 发行版。如果 OpenJDK 存储库也托管在同一提供商上，这可以促进更密切的协作。

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

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

为什么选择 GitHub？

选择 GitHub 的动机是它在选择外部提供商的所有三个主要原因上都表现出色。 GitHub 的性能与其他提供商一样好或优于其他提供商，它是世界上最大的源代码托管服务（截至 2020 年 5 月拥有 5000 万用户），并且拥有最广泛的 API 之一。

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

• Emacs（magit插件+ forge插件）
• VS Code（GitHub Pull Request插件）
• 原子（内置）

以下集成开发环境 (IDE) 支持与 GitHub 上的拉取请求交互：

• IntelliJ（内置）
• Eclipse（GitHub Mylyn 连接器）
• Visual Studio（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 建议使用Skara 项目中开发的工具支持多个工作流程。贡献者将能够选择最适合他们的工作流程：

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

当然可以混合和匹配不同的工作流程。对于像 OpenJDK 这样庞大且多样化的开源社区，各个贡献者的工作流程的唯一共同点是它们有所不同。在描述各种工具和服务之前，我们首先介绍一个合并新变更的工作流程示例。 （更专业的任务的工作流程，例如存储库之间的同步或添加标签，将在此 JEP 的未来修订版中讨论。）

工作流程

所有四个工作流程的共同点是每个更改都以拉取请求 (PR) 开始。 PR 可以通过多种方式创建——从 CLI、Web 浏览器、文本编辑器或 IDE。但是，创建 PR 需要GitHub上的帐户。对于不希望在GitHub上创建帐户的贡献者，我们将继续接受发送到 OpenJDK邮件列表的补丁。然而，此类补丁需要拥有GitHub帐户的贡献者来创建 PR，类似于当今有多少贡献者帮助新人创建 webrev 并将其上传到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 中的提交更改的源代码区域自动标记。例如，对jdkmaster存储库中的分支的 PR，其中目录和目录均发生更改，从而获得标签和.自动生成的 RFR 电子邮件将发送到邮件列表以及PR 作者指定的任何其他列表。 RFR 电子邮件包含 PR 的标题和正文、自动生成的 PR 提交摘要以及自动生成的 Webrev 的链接。make``src/hotspot``build-dev``hotspot-dev``build-dev@openjdk.java.net``hotspot-dev@openjdk.java.net

审阅者现在可以使用多个工作流程讨论 PR 中的更改：

• 通过回复发送到邮件列表的 RFR 电子邮件，在这种情况下，回复内容将复制到 GitHub 上的 PR（不需要 GitHub 帐户）；
• 通过网络浏览器使用https://github.com/上的审核工具；
• 通过使用与 GitHub 集成的各种文本编辑器和 IDE 中的审阅工具；
• 通过使用与 GitHub 集成的图形桌面应用程序；或者
• 通过使用 Skara CLI 工具。

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

如果 PR 作者根据审阅者的反馈将其他提交推送到源分支，则机器人会发送对 RFR 电子邮件的回复，包括新提交的自动摘要以及自动生成的增量和完整 Webrev。

由于审阅者对更改感到满意，他们将 PR 标记为已审阅。这可以通过以下方式完成：

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

一旦所有审稿人都满意，PR 作者就可以最终整合 PR。他们通过添加具有确切内容的评论来做到这一点/integrate，之后发生了许多事情：

1. 机器人将所有提交压缩（折叠）为一次提交。
2. 如果有必要，机器人会在目标分支之上重新调整压缩的提交（通常master）。
3. 机器人为最终提交构造一条提交消息，其中包括：
   • PR 的标题作为提交消息的标题，
   • 基于 PR 评论的正文，以单词 开头/summary，
   • 所有审阅者的 OpenJDK 用户名都添加到Reviewed-by:预告片中，以及
   • 所有合著者都在Co-authored-by:预告片中添加了内容。
4. 机器人将生成的提交推送到目标分支（通常master）。

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

如果 PR 的作者不是 OpenJDK Committer，则该标签sponsor会在作者/integrate在评论中发出命令后添加。然后， OpenJDK提交者必须在新注释中键入/sponsor命令才能集成 PR。

权限和角色

如前所述，我们不建议更改 OpenJDK Census，也不建议在外部源代码托管平台上对 OpenJDK 贡献者的角色和权限进行建模。相反，服务器端工具（“机器人”）维护 OpenJDK 贡献者的 GitHub 用户 ID（不是用户名，因为不稳定）到 OpenJDK 用户名的映射。结果是，机器人可以检查 PR 的作者是否是 OpenJDK作者，或者 PR 的审阅者是否是 OpenJDK Reviewer。该模型独立于外部提供商。这也意味着无需在外部提供商上复制 OpenJDK Census数据。

工具

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

• git-fork：在外部提供商上分叉一个项目并克隆它
• git-pr：更新、批准、获取、显示等，拉取请求
• git-sync：从上游存储库同步分支
• git-publish：将本地分支发布到远程仓库
• git-info：从提交消息中提取特定于 OpenJDK 的信息
• git-token：与 Git 凭证管理器交互以处理令牌
• git-proxy：通过 HTTP(S) 代理代理来自 Git 命令的所有网络流量 - 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：将所有 PR 元数据以 JSON 格式存档在 Git 存储库中
• forwarder：将推送的提交转发到其他存储库（例如沙箱）
• jbs：更新JBS（类似于现有的“hgupdater”服务）
• submit：作为机器人实现的测试服务示例

服务

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

• OCA_服务减轻了审阅者检查贡献者是否签署_Oracle 贡献者协议的负担。

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

备择方案

• 继续使用 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和一些代码工具项目。这些项目提供了工具、机器人和服务的实际测试，以确保可以以较低的摩擦完成进一步的项目转换。

风险和假设

切换到外部源代码托管提供商的主要风险是 OpenJDK 社区可能会变得依赖于该提供商。由于 Git 的分布式特性，版本控制数据本身始终独立于提供者。然而，存在这样的风险：代码审查注释等元数据可能被锁定到特定的提供者。还存在工具和工作流程可能变得依赖于特定提供商的风险，因此由于工具中所做的假设而无法更改提供商。

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

• 拉取请求中的所有讨论都会复制到相应的 OpenJDK邮件列表。

• Pull 请求中的所有讨论都以两种格式存档：mbox（供人类使用）和 JSON（供软件使用）。

• 推送通知被发送到相应的*-changes@openjdk.java.net邮件列表，从而避免对提供商的 RSS 提要的依赖。

• OpenJDK Census用于用户组织和权限级别，从而避免对提供商的用户组织工具的依赖。

• 域https://git.openjdk.java.net/重定向到 OpenJDK 社区当前的源代码托管提供商。JBS 问题和邮件列表消息中记录的源代码 URL使用此域而不是当前提供商的域。

为了防止 Skara 工具依赖于特定提供商的 API，从一开始就严格要求支持多个外部提供商。所有工具还需要与开源GitLab 社区版(GitLab CE) 配合使用。

依赖关系

• JEP 296：将 JDK 森林合并到单个存储库中
• JEP 357：从 Mercurial 迁移到 Git