如何写一份好的 Changelog

更新日志的可读性也是我们 SDK 质量的核心指标之一，因为这是开发者首先会看到的「门面」——在他们下载或升级之前，都会看一下 changelog，看看 SDK 的进展是否满足他的需要。
我们要提高 SDK 稳定性，要在每个版本发布的时候主动通知用户，以期望他们能尽快跟进升级，changelog 就是我们最好的宣传单。
我们先来看几个例子：

3.2.4 发布日期：2016-02-16
1. 完善 IM 模块的异常处理机制：处理了当 sendMessage 后，服务端返回的 ack 和 session 包含异常信息的情况。
2. 完善单点登录的异常处理机制：允许在未上传 deviceToken 前就进行 openClient，但是当下一次携带 deviceToken 进行 openClient 操作时会触发 [id client:didOfflineWithError]，开发者需要在此代理方法中，调用 [AVIMClient openWithOption:callback:]，并将 AVIMClientOpenOption 的 force 属性设为 YES，重新登录。
3. 禁用了获取 MAC 地址的功能

这里有什么问题呢？
在第一个改进里面，服务端返回的 ack／session 这是我们的内部实现，用户是看不懂的，从这个描述里面，作为一个用户，我不知道：sendMessage 之后会出什么异常（应用层的表现是什么），在什么场景下会出现这个异常（有多大概率会出现这个异常）。
在第二个改进里面，能从用户的角度来描述问题并给出详细的解决方案，这比第一个要好了，但是我还是不明白，单点登录的异常处理机制「完善」在哪里。从后面的描述来看，给出了一个「在未上传 deviceToken 前」进行登录的解决办法，但是是不是之前版本一定要在上传 deviceToken 之后才进行登录？之前版本存在什么问题？这都没有讲，把新的解决方案贴上来，并不能代替对问题本身的说明。并且，具体的解决方案（这个方案本身我觉得也不够优雅，为什么不能自动重连一次呢？当然这是后话）可以放到我们文档中去，这里给出到文档的链接比较好。
在第三个改进里面，「获取 MAC 地址」这个提法很奇怪，我们 SDK 从未说明有这一个「功能」，这只是一个内部的实现细节，而为什么需要禁用（可能涉及到用户是否要跟进升级），没有说清楚。

当然，我们也有写的好的例子，譬如这个：

3.13.4 发布时间:2016-02-16
1. 修正 AVUser.resetPasswordBySmsCodeInBackground 在执行正常的时候, callback 并不在 MainLooper 的问题

这里清楚说清楚了调用什么 API，什么情况下出现什么问题，简单明了。

那么，究竟要怎样才能写好一份更新日志呢？
最主要的一点，就是考虑一下目标受众的感受。大家可以角色互换一下，你是 LeanCloud 的用户，看到了 LeanCloud 发出来的 changelog 之后，你会有什么感觉。对于每一份 changelog 我们都需要注意以下几点：
1，changelog 是给人看的，不是机器，所以，首先要说人话。什么叫「人话」呢，就是要求语句通顺，能够简单明了说清楚「用户能够明白」的事情，这里「用户能够明白」而不是我们自己明白，这一点很重要。我们需要站在用户的角度，让一个使用者，一个对内部实现不甚了解的人，能明白这一次的更新内容。尤其不能做的是，把 git 日志直接扔到更新日志里。
2，对于有些 bug，我们要斟酌一下该怎么说用户才能明白，特别地对用户上报上来的 bug，我们则需要提及用户名，说清楚解决了 xxx 反馈的 bug（并对 bug 表现和影响范围进行说明），给关心我们产品的用户一个交代，同时也展示一个积极解决问题的态度。
3，对于有些升级或优化，如果你希望用户马上使用，那么记得在 changelog 里面说一下效果对比。就像 mongo 3.0 发布的时候，要是不说「写性能提升 7-10 倍，存储空间减少 80%」，这个版本应该不会有多大动静，大家也不会对升级有什么期待。相比之下，我们的 changelog 则含蓄羞涩的多：「底层数据传输协议由 JSON 改为 protobuf，让数据传输更有效率」。
4，changelog 的内容组织要清楚明白，我们可以定一个模版，以后都按照同样的方式来组织内容，就像我们每月的「与用户书」一样。我想这个模版里面需要包含如下几个部分：

• Added － 这里记录新增加了哪些功能／接口
• Changed － 功能／接口变更
• Deprecated － 不建议使用的功能／接口，将来会删掉
• Removed － 之前不建议使用的功能／接口，这次真的删掉了
• Fixed － 这里记录解决了哪些问题
• Others － 这里记录性能优化和安全性增强等改进。

我们的质量提升行动，就从一份更好的更新日志开始吧。