从Jira到GitHub，详解Spring Framework问题跟踪系统的迁移过程

Spring Framework 已经将整个问题跟踪系统从 Jira 迁移到 GitHub，本文将介绍这次迁移的背景和相关的细节。

迁移细节

Spring Framework 整整 15 年的问题和相关注解都已经被导入 GitHub，这样的一个迁移需要考虑很多事项，接下来将介绍其中的一些细节。

链接

指向现有问题的链接，例如https://jira.spring.io/browse/SPR-16751，将被重定向到相应的 GitHub 问题上。如果你确实想要转到 Jira，可以在 URL 后面加上 redirect=false。导入到 GitHub 的问题都会有一个指向 Jira 来源的链接。

Jira 问题的名字，例如“SPR-16751”，被替换成 GitHub 的命名方式，这有利于在时间表中插入链接，而且当鼠标悬停在链接上时，可以进行初步预览。

其他 Spring 项目的 Jira 问题的名字，例如“DATAJPA-813”，也被替换成链接。例如，#18558 指向 Spring Data JPA，#20904 指向 Spring Data MongoDB，#16906 指向 Spring Integration Extensions。

在迁移之后，时间表中就会包含指向 Spring 的问题链接，可以通过鼠标悬停在链接上进行预览。例如，#21362 指向 Spring Boot，#20849 指向 JUnit，#20256 指向 Jackson。

到其他 GitHub 项目代码的链接也同样会获得这些好处。

Jira 的详细信息

每个被导入到 GitHub 的问题都会在其描述的下半部分显示原始的 Jira 信息。也就是说，来自 Jira 的所有信息都可以在 GitHub 上获得，不必在两者之间来回跳转。你可能会看到以下的一项或多项内容：

• 受影响的版本；

• 参考URL；

• 附件；

• 子任务和相关问题；

• 拉取请求和提交；

• backport版本；

• 投票数和关注者数量。

但请注意，投票和关注订阅无法被转移到 GitHub。即使 spring-issuemaster 拥有完全权限，它也只能投一次票。因此，用户需要请访问 GitHub 并重新订阅，这样才能接收到特定问题的更新通知。

标签

一些 Jira 字段被转换为 GitHub 问题标签。

另外两个标签也适用于导入的问题。

我们利用这个机会简化了 Jira 字段的值，例如 Jira 中组件的 25 个值对应于 GitHub 中“in：”标签的 5 个值。“status：”和“type：*”标签的值也已经过修改。

我们选择的标签与 Spring Boot 中使用的标签保持一致。Spring Boot 团队已经针对他们的过程和标签做过很周全的考虑，在这里可以查看完整的标签集。

在 Jira 中，很多字段和标签都是可修改的。但在 GitHub 中，只有贡献者可以添加或删除标签。这很有道理，因为问题报告者只需要描述问题，然后让贡献者对其进行分类。开发者和贡献者都可以使用标签进行搜索。

修复版本

一个 GitHub 问题只能有一个目标里程碑（即“修复版本”），而一个 Jira 问题可以有多个修复版本。这感觉就像一个缺点，但它迫使我们考虑做出一些有意义的调整。

例如，SPR-17226 有修复版本“4.3.19”、“5.0.9”和“5.1 RC3”，而导入的问题 #21759 将“5.0.9”作为目标里程碑，将“4.3.19”作为 backport 版本。这样很完美，即问题是在当前的生产分支（截至 2018 年 8 月的 5.0.x）而不是预发布的“5.1 RC3”版本中得到修复的。我们打算在即将到来的 5.2 开发周期中遵循这一流程，在当前生产分支（5.1.x）修复问题，然后合并到 master（面向 5.2），在这个时候可能有少量问题需要 backport 到 4.3.x.

对于历史性的 backport 问题，我们为每个版本的 backport 问题创建了一个问题引用，总共大约有 45 个。在未来，我们打算使用单独的问题来代表 backport 问题。这些问题将被自动创建并用于发布跟踪。

标记

毫无疑问标记是整个迁移过程最大也是最痛苦的部分。15 年的问题跟踪历史反映出了编程风格的重大转变，而这反过来决定了注解中会出现什么样的内容。

例如，人们最开始直接将 XML 粘贴在注解中，Markdown 会将它们视为 HTML 块，导致标签无法正常显示。当然，如果它们被包含在{code:xml}…{code}中看起来会好很多，但在那些日子里，人们并不经常使用这个标记，不管怎样总是会出现 XML 片段，给正常迁移带来了很大麻烦。

还有很多其他错综复杂的问题，比如转义花括号来避免出现单空格效应，或者转义星号以防止它们被当作粗体标记。我们付出了很多努力来确保高质量的标记转换。

需要特别说明的一个问题是在纯文本中（即在代码块之外）使用“@”。这个符号用于给 GitHub 用户触发通知。令人感到惊讶的是，居然有人使用 @Bean、@Configuration、@Component 作为 GitHub 用户名，像 @andy、@arjen、@brian 与 GitHub 用户名冲突的情况也很常见，所有这些对于导入带有注解的 17K+个问题来说都是一个巨大的麻烦。这就是为什么我们要对它们进行转义。在未来，在创建新问题或注解时，请使用反引号，例如： @Foo。

迁移背景

我已经使用 Jira 很长时间了，也很喜欢它。迁移到 GitHub Issues 并非突发奇想。转向 GitHub 并不是因为它的功能，虽然我必须承认从迁移到 GitHub Issues 开始，它们确实对我产生了一定的影响。

GitHub 是几乎所有开源项目的所在地，包括所有的 Spring 项目，并且几乎所有用户都有一个 GitHub 账号。因此，让开发人员为他们所依赖的每个开源项目或问题跟踪器使用单独的登录账号有点不切实际。

另外，将源代码和问题放在同一个地方也有好处，比如可以在单个项目或者 GitHub 的所有项目中自动链接引用问题、拉取请求、源代码和源码提交，并且可以在注解等地方提及和通知 GitHub 用户。所有这些好处是单独的问题跟踪系统无法提供的。我怀疑是否有人想要回到过去，那个时候开源项目托管在不同的地方。对于问题跟踪系统来说也是一样。

将源代码和问题跟踪系统放在一起有更深层次的好处，这些好处可能没有那么显而易见。GitHub 对问题和拉取请求同等对待，使用了同一个序列号为它们分配编号。它们看起来是一样的（描述、注解、标签和目标里程碑）。它们都出现在发行说明中，几乎完全一样。拉取请求只不过是附加了源代码提交的问题。

在 Spring Framework 的历史上，我们坚持每个拉取请求都对应一个 Jira 问题。我们也不喜欢这种负担，但我们需要一个系统来记录所有的问题。由于存在这种分裂的情况，哪些东西应该针对拉取请求以及哪些应该属于 Jira 问题，一直以来都不太明确。

但在未来，这不再是个问题。我们期待同时只有一个问题或者拉取请求，而不是两者都有。如果你要讨论问题，建议先创建一个问题，如果稍后提交了拉取请求，拉取请求将取代问题。这两者仍然会关联在一起，不会丢失任何内容。

标记是一个不容忽视的问题。毫无疑问，我认为 Wiki 标记对于与代码相关的注解来说是一个痛点。我已经用它好几年时间了，而且几乎每天都用。我已经习惯了，但有些标记使用起来仍然很麻烦，需要付出很大的努力。这里顺便提醒一下，在代码片段中显示像花括号和星号这些常见的符号时需要这样：{{/endpoint/{server-id}/{session-id}/{transport/*}}}。

在与代码相关的注解中使用 Markdown 会更容易些。它需要更少的输入，在格式化代码方面也没有什么问题，因为它更简单，并且不会与代码中的符号冲突。我来从一开始就注意到这一点，因为我也在同时使用 GitHub 和 Markdown。我不明白为什么 Jira 仍然不支持 Markdown，但这不是一个决定性的因素。

最后，如今大多数开发人员使用了 Spring Boot，而它一直在使用 GitHub Issues。单从这个角度来看，Spring Framework 就有足够的动力进行迁移，因为 Spring Boot 不可能会迁移到 Jira，所以这是为 Spring 用户提供一致性体验的唯一方法。

实际的迁移

尽管做了很多准备工作，但实际的迁移却与预想的完全不一样。我们使用了非官方的 GitHub 导入 API（https://gist.github.com/jonmagic/5282384165e0f86ef105），API 文档中说不会触发任何通知。我们在测试期间没有发现任何问题，但在开始实际的迁移后，与问题和注解相关的通知如洪水般涌入。

我们通过各种渠道与 GitHub 支持团队取得联系。所幸的是，他们也注意到了这个问题。他们怎么会注意不到？根据我的估计，在我们撤消之前导入的 2,600 个问题应该会产生数千万封电子邮件，所以导致通知系统中断一点也不足为奇。

一天后，在 GitHub 支持团队修复了问题并关闭了 Spring Framework 项目的所有通知后，我们很顺利地在 8-9 小时内导入了所有问题。随后，我们花了几个小时使用 GitHub 的名称格式替换了 Jira 的问题名字，还花了几天时间检查和清理标记转换问题。

英文原文：https://spring.io/blog/2019/01/15/spring-framework-s-migration-from-jira-to-github-issues