wenliangdai

如何给你的开源项目编写有用的变更日志 - The ClojureWerkz Blog

wenliangdai · 2016-12-20翻译 · 829阅读 原文链接

TL;DR(简单地概括)

一个有用的项目变更日志可以回答一下三个问题:

  • 这次变更是否重要,从而决定是否更新

  • 这次发布是否向前兼容(兼容以前的版本)

  • 改变了什么,以及为什么做出这些变动

一个覆盖了这三个要点的变更日志将帮助你的用户更快的接受新版本,甚至是在一些非常保守的公司环境里。同时它也可以让技术人员对你的项目更加尊重。

开始之前

今年四月我们写了一些 我们认为做一个优秀的开源软件所需要的东西

这篇博客收到了很多积极的回应。今天我们将深入探讨维护一个项目的其中一个方面:编写优秀的变更日志。

开始之前,先让我提醒你一个可以适用于开源软件任何方面的第一要点:

> 别让你的用户抓狂

也叫作

> 别让你的用户想要砸电脑

同学,你真的写变更日志吗?

除了经常需要花费大量精力去编写地精美的文档,一个好的变更日志(在我们的观点里)是第二重要的事情来赢得你的用户对项目的信任度。

不幸的是,GitHub 上大部分开源项目压根都没有一个变更日志。

如何编写一个好的变更日志

在讨论如何维护一个好的变更日志之前,先来定义什么是「好」。对于一个变更日志来说,好意味着可以提供有效的信息。什么样的信息是一个用户希望看到并且想要去更新的?这对于每个人都不尽相同,但总体包含以下几点:

  • 这次发布是否重要?我是否应当立即更新,或者可以等一等?

  • 这次发布是否向前兼容?更新之后是否仍能正常运行?

  • 改变了什么?为什么?如何使用新的东西?

这几点对于操作项目的技术人员来说至关重要,因为当系统某些地方运行失败时,他们需要半夜起床来处理问题。一个好的变更日志对于开发者和技术工程师都十分重要。

技术操作人员会关心的事情

就像我们之前所提到的,如果一次更新破坏的原先的系统,那么他们可能需要半夜来处理问题。如果类似问题在你的开源项目里多次发生,那么一下两件事情将很可能会发生:

  • 你的项目将尽可能不被更新

  • 你的项目将尽可能被避免使用

作为一个运维人员,糟糕的事情时有发生。所以不要冒险去惹怒他们。让他们有信心去更新你的项目并不会花费很久。你要做的只是清楚地记录这次更新有哪些会破坏原先代码的改变(不兼容的地方)

对于你的项目来说,时而发布一些导致使用方法跟之前不同的更新时可以接受的。只需清楚地发布并在变更至日里记录改变了什么即可。

然后需要提到的是这是否是一个非常重要的更新。使用语义化的版本号可以帮你更好地表现更新的重要性(大多数更新都不是非常重大的,但是重要的更新可以是修复了关键性的 bug 或者一些安全问题)。

在某些情况下,你修复的一个 bug 可以影响到很多人。这点应当在日志中提到。在其它某些情况,更新只会影响很小一部分人群,比如在某个不常见的硬件架构中运行某个特定 OpenBSD 版本的人,或者一次很小的修补。在这些情况下,在日志中提到只会影响到小部分特定场景和人群是一个很好的做法,这可以使你的用户更快的去更新。

一个常见的破坏现有设定的(会使技术人员担心的)例子是,你对某个特定版本不再继续提供支持。比如,上个月开始我们的项目已经逐步开始支持 Clojure 1.3。不提及类似的变动相当于在背后捅了你的用户一刀。

例子 1

Langohr 1.5 变更日志 清楚地记录了 Clojure 1.3 将不再被支持。

例子 2

对于 Cassaforte 1.0.0-rc4 我们决定需要对代码的一些命名空间做出改动。在项目的后期做出这种破坏 API 的是不好的,但它仍处在 pre-1.0 阶段所以我们决定去做。我们知道 Cassaforte 已经拥有了一些用户,所以我们在那次的发布的变更日志里的第一行加粗记录了这些破坏性的变动。

例子 3

我们从来不在 ClojureWerkz 项目的变更日志里说是否所有人都应改更新,但我(@michaelklishin)会尽量在我的其它项目中这么做。我们同时会在项目发布公告里提到这些。

无论什么时候,如果你在日志里提到了哪些人群可能会被影响到,这可以给你的项目加分。

总结

你可以注意到,在日志中清楚地说明有哪些重要的变动别不会花费太多精力。实际上,他们通常只占一行文字。你可以用很少的碎片时间来做这件事,也就是你读读新闻头条那么多的时间。不要找借口

开发者们关心的事情

开发者们需要从变更日志里获取更多的信息。当然,让他们了解有哪些破坏性的变更也同等重要。但是开发者们可能更关心发布了哪些新的特性。

然而,只提及这次发布里有一个新的特性 X 是不够的。你需要让人们能够轻松地理解如何使用它。这意味着文档也要做到同步更新,同时在变更日历里提供一些例子。

下方是一些来自 Monger, Langohr 和我们自己的项目的例子.

例子 1

One More Cache 的实现

monger.cache/db-aware-monger-cache-factory 将返回一个 MongoDB 备份的 clojure.core.cache 实现可以使用任何数据库:

(require '[monger.core  :as mg])
(require '[monger.cache :as cache])

(let [db   (mg/get-db "altcache")
      coll "cache_entries"
      c    (cache/db-aware-monger-cache-factory db coll)]
  (comment "This cache instance will use the altcache DB"))

例子 2

更方便的发布者确认支持

langohr.confirm/wait-for-confirms 是一个新的方法,它会等待直到发布在某个已知频道的消息的确认信息到达。它可以接受一个定时器:

(langohr.confirm/wait-for-confirms ch)
;; wait up to 200 milliseconds
(langohr.confirm/wait-for-confirms ch 200)

例子 3

对于默认数据库的身份认证

monger.core/authenticate 现在有了一个二元版本,它将对默认数据可进行身份认证:

(let [username "myservice"
      pwd      "LGo5h#B`cTRQ>28tba6u"]
  (monger.core/use-db! "mydb")
  ;; authenticates requests for mydb
  (monger.core/authenticate username (.toCharArray pwd)))

如何避免写变更日志

你会经常发现一个项目里有ChangeLog.md文件,里面写着“去 git 日志里看变更日志”。

除非你写了非常详尽的提交信息(commit messages)和合并分支信息,否则那不是一个变更日志。那只是在对你的用户说“去你的吧,自己去弄明白,我不欠你任何东西”。不要成为这样的人。

说在最后

可以看出,把一个无用的项目日志变成一个可以帮助你的用户的日志并不是一件难事,同时它可以反过来帮助你的项目被更好的采用。

Michael.

译者wenliangdai尚未开通打赏功能

相关文章