从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标签
Issue Type	“type: *”
Status	“status: *”
Resolution	“status: *”
Component	“in: *”

GitHub标签	描述
“has: votes-jira”	导入的问题包含10个以上投票
“has: backports”	包含backport版本的问题

修复版本

一个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