发布了一款库(或工具包),如何持续地编写更新日志(ChangeLog)?

发布了一款库(或工具包),如何持续地编写更新日志(ChangeLog)?

2018-08-05 09:35

据说程序员最讨厌的两件事是 “别人没有写文档” 和 “要我写文档”。

编写更新日志可是也落入此怪圈呢!


程序员不写文档

来自 GitHub 的开源调查问卷结果直接显示,最令人头痛的莫过于文档了:

Incomplete or outdated documentation is a pervasive problem, observed by 93% of respondents, yet 60% of contributors say they rarely or never contribute to documentation. When you run into documentation issues, help a maintainer out and open a pull request that improves them.

▲ 来自 http://opensourcesurvey.org

自动化

我曾经试图找到一些自动化的方式来生成更新日志,例如:

  • 查找 git 提交日志
  • 查找 issues 问题

然而,这样生成的日志真难看懂!不信你试着把一个项目的 Issues 列表读一遍?

更新日志应该包含哪些内容

站在库的使用者的角度来看,程序员们希望看到什么样的更新日志,不希望看到什么样的更新日志?

  1. 添加的接口
  2. 现有接口的改变
  3. 未来即将删除的接口
  4. 此版本已经删除的接口
  5. 此版本修复的 Bug
  6. 此版本的安全性改进

然而这些都写了会让编写者很痛苦的……

手工和自动化的结合

当存在 API 比较工具的时候,我们可以很容易地比较各个版本间 API 的变化,包括新增、改变、即将移除和已经移除。而这部分的内容由工具生成是没什么阅读障碍的。

另一部分,描述功能的手工编写会比较容易阅读。例如新增的功能、修改的功能、已经删除的功能。

优秀文档的参考

以下是 UWP 的开发文档,属手工和自动化结合生成。

本文会经常更新,请阅读原文: https://walterlv.com/post/how-to-write-changelog-and-keep-it-updating.html ,以避免陈旧错误知识的误导,同时有更好的阅读体验。

本作品采用 知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议 进行许可。欢迎转载、使用、重新发布,但务必保留文章署名 吕毅 (包含链接: https://walterlv.com ),不得用于商业目的,基于本文修改后的作品务必以相同的许可发布。如有任何疑问,请 与我联系 (walter.lv@qq.com)

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏企鹅号快讯

使用Redis走进误区,该怎么办?

首先是一个产品线开发人员搭建起了一套庞大的价格存储系统,底层是关系型数据库,只用来处理一些事务性的操作和存放一些基础数据; 在关系型数据库的上面还有一套Mong...

29590
来自专栏13blog.site

Docker+SpringBoot+Mybatis+thymeleaf的Java博客系统开源啦

作者:13 GitHub:https://github.com/ZHENFENG13 版权声明:本文为原创文章,未经允许不得转载。 个人博客 对于技术...

53090
来自专栏娱乐心理测试

关于小程序的一些基本常识

    a. 如果小程序需要与你的服务器进行数据交换,那么你就必须注册域名,即使是开发环境也需要;

14330
来自专栏企鹅号快讯

新人分享系列-蘑菇街主搜Dump拼装服务演化

花名:长文 部门:算法中心搜索业务组 入职时间:2016年 主要从事蘑菇街搜索引擎实时增量商品信息补全以及搜索业务接入 一、引言 搜索引擎作为电商平台的主要入口...

413140
来自专栏杨建荣的学习笔记

总结nmon的诸多优点 (r4笔记第78天)

nmon在平时的工作中可能会多多少少接触到,从sourceforge上能够下载到nmon的包。可能是有着IBM的血统,这个工具对于AIX的支持力度要大得多。 当...

36780
来自专栏云计算D1net

如何用渗透测试计划锁定你的云?

渗透测试是一项旨在确定和解决任何黑客可能利用漏洞的IT安全性措施。就如同传统数据中心广泛采用这一测试方法一样,很多企业的IT部门也在他们的公共云计算环境中使用着...

30880
来自专栏杨建荣的学习笔记

防火墙开通的自动化尝试和感悟

对于一个从零到一的系统或者平台,你会有几十次几百次的调试,为的是能让系统/平台真正跑起来,用起来。我想这背后需要的坚持真是百般煎熬,一方面希望能够像建造...

13310
来自专栏JAVA高级架构

微服务架构选型实践

背景 随着公司一年多的成长,我们已经开发了数十个项目了,后台有 JAVA 的有 PHP 的,为了更好地提升开发与管理效率,各技术大牛小牛们时常进行激烈的 PK,...

56360
来自专栏FreeBuf

如何写好一篇漏洞报告(国外篇)

如何写好一篇漏洞总结报告,这一直都是一些应用开发公司经常忽略的重要事情,一篇好的漏洞总结报告可以有效帮助开发人员,减少寻找和解决漏洞的时间。 接下来我就开始讲述...

48770
来自专栏JAVA技术zhai

优化不易,且写且珍惜!

本文要感谢我职级评定过程中的一位评委,他建议把之前所做的各种性能优化的案例和方案加以提炼、总结,以文档的形式沉淀下来,并在内部进行分享。力求达到如下效果:

45870

扫码关注云+社区

领取腾讯云代金券