构建一个 Ruby Gem 第七章 更变日志

如果你的 gem 被用的足够多, 用户将会依赖它们的特性。作为一个维护者，我们已经能控制如何管理发布和贡献者。在这一章中，我们会探讨典型的更新日志的内容和为什么要使用更新日志。

为什么要包含一个更新日志?

Github 用它的特性把我们宠坏了，它让我们依赖于它的 UI 比如近期提交和 bug 历史。 然而，当功能或者外部 API 被改变时，记录并且把它们和一个版本联系起来是有价值的，贡献者（如果不是你的话），或者一个 pull request 或者 issue number 都是适用的方式。 虽然 README 文件是当前版本功能的最好文档，它不能说明一路过来的变化。

查看一个项目的提交列表不一定总是能展示所有的历史。由于这个原因，很多项目都维护一个文件 CHANGELOG.md 或者 CHANGES.md 在根目录下。 这个更新日志记录了一个用户应该关心的不同版本的 API 和特性。就像 README.md 文件一样，这个文件通常使用 markdown 来书写内容，使得它易于在 Github 上被查看。

下面是我的 gem Sucker Punch 的 CHANGES.MD 文件的摘录。

  0.3.1
  -----------

  - Fix location of inline testing library

  0.3
  -----------

  - Now includes a testing library that will run all jobs synchronously.

通常来说，把版本号作为标题，所有的关于这个版本的更新都使用要点和示例代码（如果必要）来记录。

如果一个 gem 足够庞大，那需要定期关联一个特定的 pull request （或者 issue）和贡献者来体现它的价值。这不仅能分辨贡献者和他的工作，也能说明对应代码负责人是谁。

现实世界中的例子

Sidekiq有一个很好的例子，一个更新日志文件包含了 pull request 编号和贡献者的名字在 Github 上。

ActiveRecord 也有一个详细的更新日志包含相关的 issue 编号和贡献者。

总结

虽然一个更新日志不是我每天都想着要做的事情，如果我们频繁地从其他开发者中获取贡献并且定期发布我们的 gem 的新版本，为更变写文档是值得的。

更新日志不仅仅适用于 Ruby gems 也可以被其他软件系统用于增量发布。我已经把它们用在多种需要跟踪意料外的功能变的情况下了。 这也能用 git 提交日志来实现。然而，如果你不熟悉项目的代码，单个的 git 提交用处就很小了。 在下一章，我们会讨论一个开源项目的贡献者的责任和我们如何提供价值反馈给 Ruby 社区。