自动生成变更日志

本文是Fueled上有关构建自动化的一系列博客文章中的第一篇。 更多即将推出！

在Fueled，正确的变更日志对所有从事项目的团队都很重要：

• 质量检查团队，使他们知道可以测试什么
• 客户和项目经理，以便他们知道已完成的工作
• 开发人员，以便他们可以快速参考所做的工作

我们全年采用了一种相当敏捷的方法来改进变更日志，以达到今天的状态。 我希望与您分享迄今为止我们在流程中取得的一些主要收获，并就我们可能会继续改进的地方提出一些建议。

---

我们最初的方法是只为客户构建简单的变更日志，并在内部依靠适当的Jira故事更新来跟踪项目的状态。 尽管此方法行之有效，但是却需要有人编写变更日志并手动更新Jira故事，而可能会忘记此处的功能或此处的错误修复。

因此我们认为：

“有没有办法使它自动化？”

那是我们了解语义提交消息的时间 。 语义提交消息允许简洁地描述提交的内容，还可以选择在提交正文中添加更多扩展的消息。

在Fueled，我们使用以下格式的提交消息：

  （）： 

其中type是以下之一：

• feat ：一项新功能
• fix ：错误修复
• 性能：性能增强
• docs ：文档更新
• refactor ：代码重构
• test ：添加/更改/删除单元测试
• style ：样式更改（更新缩进，将空格更改为制表符等）
• chore ：配置更新，代码签名更改，…
• scope是在提交中更改的应用程序的一部分。 即，如果您有登录流程，并且在那里更新了UI，则可以使用feat(login): 。 它始终以小写字母和破折号分隔单词，即video-player ， code-signing等。
• message只是一条简短的命令性消息（至少少于80个字符），描述了提交中的操作（就像您告诉项目的操作一样）

以下是一些来自我们项目的示例：

• feat(settings): add button allowing user to log out
• fix(offline-mode): fix issue where success popup would not display properly on iphone 6+
• perf(video-player): improve video playback performance by leveraging GPU
• docs(readme): add architecture information
• refactor(settings): de-dupe duplicated code
• test(api): add tests related to API model parsing
• style(*): convert spaces to tabs
• chore(code-signing): fix code-signing issues

使用语义提交消息有一些优点：

• 它迫使您将功能和错误修复与提交分开
• 从而使提交内容小而集中
• 从而使通过bisect进行调试更加集中
• 它允许您将这些信息提取到变更日志中
• 它允许团队和项目之间的一致性

显然， 这仅在人们对每次提交都采用和使用此消息格式的情况下才有效。 在接下来的几周内，我们在Fueled引入了这种格式，每个Fueled开发人员都在使用这种格式-无论是在我们的iOS，Android，Web还是API团队中。

语义提交消息的 语法在很大程度上受 Karma的Git Commit Msg以及其他来源的启发 。

一旦每个人都使用了此提交消息语法，就可以规范给定项目的作用域，以便可以正确且一致地生成更改日志。 由于我们使用Jira进行项目管理，并且每个项目都有至少一个Jira板，因此我们决定将范围与Jira史诗相关联-范围只能引用Jira史诗（以小写字母标准化的小写字母）。 我们进一步详细说明了该规范，并允许人们使用斜杠/定义更详细的范围或在必要时直接定义Jira故事。

因此最终的规格变为：

• 范围一定是史诗般的
• 可以在斜杠/后指定嵌套范围
• 吉拉的故事可以指定为史诗（如果与之关联），也可以指定为嵌套范围
• 允许指定多个嵌套范围，并用逗号分隔,

这套简单的规则允许对给定功能的提交尽可能小，同时使我们有可能生成与应用程序中的操作完全匹配的变更日志。 例如，以下是一些示例提交：

• fix(XXX-1129): change copy for push notification
• fix(analytics/XXX-421): round geocoordinates to 4th decimal
• fix(global/XXX-742,XXX-747): fix a layout issue on iOS10 devices

---

但是，我们可以走得更远吗？

当然：我们想到了在提交消息时对其进行验证 。 Git通过在.git/hooks创建一个称为commit-msg的特定文件来允许此操作（在此处了解有关git hooks的更多信息）。 这个文件只是一个由git运行的脚本，其中一个参数是用户尝试提交的消息。 如果脚本返回的错误代码不同于0 ，则提交被拒绝。

我们着手为提交消息编写一个linter ，开发人员可以轻松集成这些提交消息（Wikipedia链接）。 该工具目前在Fueled内部，但我们正在寻求开源-请密切注意👀

最后一步是创建脚本以生成变更日志：最终脚本使用git命令（以获取提交）和GitHub API的组合来获取作者。 它生成的变更日志可以显示在HockeyApp / Fabric，GitHub和Slack上。 我们决定面向客户的变更日志应仅包括feat ， fix和perf变更，因为其他类型很少引用相关的用户案例。
例如，输入以下内容：

• fix(XXX-1129): change copy for push notification
• fix(analytics/XXX-421): round geocoordinates to 4th decimal
• fix(global/XXX-742,XXX-747): fix a layout issue on iOS10 devices
• fix(global/XXX-426): fix login CTA

正在生成以下GitHub更新日志：

（用户名是内部更改日志，因此显示在此处）

在HockeyApp上：

（用户名不是面向客户的，因此此处未显示，如果需要，此信息可在Jira票证中找到）

---

总而言之，允许自动生成变更日志有很多优点，最明显的是语义提交消息。

希望您发现这篇文章有趣，并继续关注！ 我们将很快探索如何使用此棉絮将消息直接显示为PR上的注释，以及我们正在做的其他检查以确保始终提供高质量的代码。