领先一步
VMware 提供培训和认证，助您加速进步。
了解更多Spring Framework 从 Jira 迁移到 GitHub Issues
Spring Framework 已将其全部 Issue 历史从 Jira 迁移到 GitHub。这篇博文旨在为您提供有关此迁移的背景信息和详细信息。
迁移详情
Spring Framework 超过 15 年的全部 Issue 及其所有评论都已导入到 GitHub。在这样的迁移中有很多需要考虑的地方，所以让我们来大致了解一下细节。
链接
如果您有指向现有 Issue 的链接，例如 https://jira.spring.io/browse/SPR-16751，您将被重定向到相应的 GitHub Issue。如果您确实想访问 Jira Issue，请附加查询参数 redirect=false。在 GitHub 端，导入的 Issue 包含一个指向其原始 Jira Issue 的链接。
文本中出现的 Jira Issue Key，例如“SPR-16751”，已替换为 GitHub Issue 引用，这有利于在 Issue 的时间线中插入双向链接。另一个好处是鼠标悬停在链接上时会显示迷你预览。
文本中出现的指向其他 Spring 项目的 Jira Issue Key，例如“DATAJPA-813”，已替换为链接。例如，请参阅 #18558（包含指向 Spring Data JPA 的链接）、#20904（指向 Spring Data MongoDB）和 #16906（指向 Spring Integration Extensions）。
文本中出现的指向其他 GitHub 项目 Issue 和 Pull Request 的链接也会获得自动优势。迁移后，被引用的 Issue 时间线中会包含指向 Spring Framework 的链接，并且您在鼠标悬停时会看到链接预览。例如，请参阅 #21362（包含指向 Spring Boot 的链接）、#20849（指向 JUnit）和 #20256（指向 Jackson）。
指向 GitHub 上任何项目的提交和源代码的链接也会获得自动优势。例如，请参阅 Issue #18463 中指向源代码范围的链接。
Jira 详情
每个导入的 Issue 在其描述的下半部分显示来自 Jira 的信息。这样做的目的是让所有来自 Jira 的信息都能在 GitHub 上获取，您无需在两者之间来回切换。如果可用，您可能会看到以下一项或多项信息：
- 受影响的版本
- 参考 URL
- 附件
- 子任务和相关 Issue
- Pull Request 和提交引用
- 向后移植版本
- 投票数和关注者数
请注意，投票和关注订阅无法迁移到 GitHub。即使 spring-issuemaster 拥有全部权限，它也只能投票一次。因此，请访问 GitHub Issue 并重新应用反应并订阅以接收特定 Issue 的更新。
标签
一些 Jira 字段被转换为 GitHub Issue 标签
| Jira 字段 | 标签 |
|---|---|
| Issue 类型 | "type: *" |
| 状态 | "status: *" |
| 解决方案 | "status: *" |
| 组件 | "in: *" |
导入的 Issue 还应用了两个额外的标签
| 标签 | 描述 |
|---|---|
"has: votes-jira" |
投票数超过 10 的导入 Issue |
"has: backports" |
包含向后移植版本的 Issue |
我们借此机会简化了 Jira 字段值，例如 Jira 中的 25 个组件值对应于 GitHub 上的 5 个 "in: *" 标签。"status: *" 和 "type: *" 标签也经过了额外的深思熟虑和修订。
我们选择的标签与 Spring Boot 中使用的标签一致。Boot 团队对他们的流程和标签进行了大量思考，我们知道这种一致性将受到许多人的赞赏。请参阅完整的标签集。
在 Jira 中，许多字段和标签是可修改的。在 GitHub 中，只有贡献者可以添加或移除标签。这是完全合理的。报告者只需描述 Issue，而贡献者对其进行分类。开发者和贡献者都可以使用标签进行搜索。
修复版本
一个 Jira Issue 可以有多个修复版本，而 GitHub Issue 只能有一个目标里程碑。这看起来像一个缺点，但实际上不止表面看到的那么多，这个限制迫使我们考虑一些有意义的调整。
以 SPR-17226 为例，其修复版本为“4.3.19”、“5.0.9”和“5.1 RC3”。尽管该 Issue 在所有这 3 个版本中都得到了修复，但没有必要污染当时仍在开发中的“5.1 RC3”的发布说明。我们可以转而说它在 5.0.9 中得到修复并向后移植到 4.3.19，而确保修复被传播到仍在开发的下一个版本是贡献者的责任。这就是它在 GitHub Issue #21759 上显示的方式。我们过去能做这样的调整吗？当然可以，但 Jira 对多个修复版本的支持并没有迫使我们去考虑。
这是一个小小的调整，它将使发布说明更简洁，但也会影响我们提交修复的方式。当下一个版本在 master 分支上开发时，我们将首先将修复应用于当前的生产分支，然后向前合并到 master，再从旧的生产分支中选择性合并（cherry-pick）。这与先将修复应用于 master，然后从生产分支中选择性合并（cherry-pick）不同。由于向前合并有助于 git 了解相关更改，因此结果是更简洁的提交历史。
至于向后移植，由于一个 Issue 只能有一个目标里程碑，我们必须创建单独的 Issue 来表示修复的向后移植。沿用同一个例子，选择“5.0.9”作为目标里程碑是值得的，因为我们只需要一个向后移植 Issue。如果我们选择“5.1 RC3”，我们就需要两个向后移植 Issue。为了让您了解这带来的巨大差异，假设 Spring Framework 从第一天起就使用 GitHub Issues。如果我们采用后一种方法，我们今天将拥有大约 2,500 个向后移植 Issue。如果我们采用前一种方法，我们将拥有大约 1,000 个。
对于历史向后移植，我们为每个版本创建了一个 Issue Holder。大约有45 个这样的 Issue。未来，我们将为所有向后移植的修复创建单独的 Issue，这些 Issue 将自动创建，主要用于发布跟踪。至于讨论，大部分对话应在主要 Issue 上进行，而向后移植 Issue 仅用于与向后移植相关的特定讨论。
标记
标记无疑是这次迁移中最大、最痛苦的部分。15 年的 Issue 跟踪历史反映了编程风格的巨大转变，这些转变反过来决定了评论中出现的内容。
例如，起初评论中粘贴了大量的 XML，Markdown 将其视为 HTML 块，导致标签完全不显示。当然，如果这些 XML 被 {code:xml}...{code} 包围，看起来会很正常，但在那个年代标记并不常用，XML 片段无论如何都会显示，这没有引起足够重视，结果导致无法正确迁移。
还有许多其他复杂之处，例如转义花括号以避免等宽字体效果，或转义星号以防止它们作为粗体标记而消失。我将省略细节。只需说我们付出了大量努力来确保标记转换的质量相当高。
一个需要强调的特殊问题是，在纯文本（即代码块之外）中使用“@”符号。在 GitHub 上，这会被视为提及用户并触发通知。您可能会惊讶地发现 @Bean、@Configuration、@Component 都是实际存在的 GitHub 用户。像 @andy、@arjen、@brian 这样的名字引用与 GitHub 用户名冲突的情况在某个时候也很常见，所有这些在导入包含评论的 1.7 万多个 Issue 时都是巨大的麻烦。这就是为什么我们小心地对它们进行了转义。今后，在创建新的 Issue 或评论时，请做一个遵守 GitHub 规则的好公民，使用反引号，例如 `@Foo`（是的，https://github.com/foo 确实存在）。
背景
我已经使用并喜欢 Jira 很长时间了。迁移到 GitHub Issues 的想法并非立即产生。相比之下，它似乎过于基础。让我彻底转变想法的原因与逐个功能的比较关系不大，尽管我必须承认，自从迁移以来，GitHub Issues 确实让我越来越喜欢。我在这里暗示的是更深层次的力量在起作用。
GitHub 几乎是所有开源项目的家园，包括 每一个 Spring 项目，而且所有用户都可以合理地被期望拥有 GitHub 凭据。因此，如今期望开发者为他们依赖或想要报告 Issue 的每一个开源项目的 Issue 跟踪器维护单独的登录凭据已变得站不住脚。
此外，源代码和 Issue 并置也带来了诸多好处。我之前已经提到了很多，例如在一个项目内以及跨越 GitHub 上所有项目之间的 Issue、Pull Request、源代码和提交之间的自动链接引用。提及并通知任何 GitHub 用户的能力。所有这些都是非常强大的优势，而孤立的 Issue 跟踪系统是无法实现的。我怀疑有人想回到开源项目托管在不同地方的时代。Issue 跟踪系统也是如此。
源代码和 Issue 并置还有更深层次、更不明显的优势。GitHub 将 Issue 和 Pull Request 等同对待。它们从相同的序列中分配编号。它们看起来相同（描述、评论、标签和目标里程碑）。它们在发布说明中没有区别地出现。Pull Request 无非是附加了提交的 Issue。
在 Spring Framework 的历史上，我们坚持为每个 Pull Request 创建一个 Jira Issue。我们也不喜欢这种负担，但我们需要一个记录所有 Issue 的单一场所。由于这种分离的情况，关于 Pull Request 下应该讨论什么以及有多少内容属于 Jira Issue 从未明确过。
今后，这不再是问题。我们期待一个 Issue 或一个 Pull Request，而不是两者都有。如果您需要先开始讨论（我们确实鼓励这样做），请创建一个 Issue；稍后，如果您提交 Pull Request，PR 将取代该 Issue。两者仍然是关联的，没有任何内容会丢失。对话只是随着行动而进行。
不可忽视的是标记问题。毫无疑问，Wiki 标记对于代码相关的讨论来说是痛苦的。我多年来每天都在使用它。我已经习惯了，但有些事情就是很难，需要付出太多努力。这里提醒一下，在代码片段中显示花括号和星号这样常见的内容需要做什么：{{/endpoint/\{server-id\}/\{session-id\}/\{transport/\*\}}}。
毫无疑问，Markdown 对于代码相关的评论更容易。它需要更少的输入，而且在格式化代码时也能正常工作，因为它更简单，并且不会与代码中常见的符号冲突。从一开始这对我来说就很明显，因为我也多年来同时使用 GitHub 和 Markdown。我一直不明白为什么 Jira 仍然不支持 Markdown。需要澄清的是，这不是一个决定性因素。它只是你学会忍受的那些事情之一，后来可能成为改变的额外动力。
最后但同样重要的是，如今大多数开发者通过 Spring Boot 使用 Spring，而 Spring Boot 始终使用 GitHub Issues。仅从这个角度来看，Spring Framework 就有足够的动力进行迁移，因为 Spring Boot 不会迁移到 Jira，而这将是为 Spring 用户创建更一致体验的唯一其他方式。
实际迁移
尽管做了大量准备，实际迁移当天还是发生了意想不到的事情。我们使用了 GitHub 非官方的导入 API，该 API 文档说明不会触发任何通知。我们在测试期间没有发现任何问题。然而，实际迁移一开始，每个 Issue 和每条评论的通知就开始蜂拥而至。
我们开始通过所有可用的渠道联系 GitHub 支持。幸运的是，他们也注意到了这个问题。他们怎么可能没注意到呢？据我估计，在我们暂停之前导入的 2,600 个 Issue 肯定产生了数千万封电子邮件，毫无疑问地导致了通知中断。
一天后，在 GitHub 支持解决了问题并为安全起见关闭了 Spring Framework 项目的所有通知之后，我们得以在 8-9 小时内顺利导入所有 Issue。又花了几个小时对所有 Issue 和评论进行了第二次检查，将 Jira Issue Key 替换为 GitHub 引用编号，然后又花了几天时间检查和清理标记转换问题。
所有这些现已完成，我很高兴地宣布，我们现在可以在 GitHub Issues 上正常使用了。