变更日志 Changelog 的书写方法

变更日志(Changelog)是软件工程中的一种常用手段,用于记录每个软件版本所发生的变更。一方面,可以方便下游及时兼容;另一方面,让协作开发者和用户了解项目进展。变更日志需要打版本号,但并不一定要遵循 Semantic Versioning。

最简单的形式

  1. 推荐使用 Markdown 语法,文件名为 CHANGELOG.md。
  2. 用二级标题标记版本号,建议标注发布日期,以便日后回溯。合并主干分支但尚未发布的,用“未发布”标题,放在开头。
  3. 对于不兼容的变化,用“破坏性变更”标记。
# 变更日志

## 未发布

- 修复 Button

## 2.0.0 - 2021-09-17

- **破坏性变更**: Table 组件重命名为 Grid

## 1.1.0 - 2021-03-21

- Card 组件支持 size (small/large/medium)
- 新增 List 和 Table 组件

## 1.0.0 - 2021-02-08

- 新增 Card 组件
- 新增 Button 组件

增加模块标记

对于模块比较多的库或应用,变更项目会很多,不容易阅读。比较好的方式是在开头标记这个变更属于哪个模块,不属于任何模块的用 Other 标记。比如说你的应用有很多页面,则可以按页面来划分。如果是组件库,则可以按组件来分。如果是单个复杂组件,则可以按属性或功能来分。

## 2.1.0 - 2021-09-17

- Card: 增加 size (small/large/medium) 属性
- List: 新组件
- Button: 修复 loading 样式
- Input: 增加 warning 图标
- Other: 修复 IE 11 兼容性

细分变更类型

实践中,分类越详细,开发者维护变更日志的工作量越大。不分类是完全可行的,只有当你有充足的时间和很高的追求的时候,再考虑。

有很多种方法可以给变更分类。

按特性(Feature)和修复(Fix)分类是最简单可行的,也更符合当下软件工程的模型,容易配合各种项目管理工具。最重要的是,通常没有什么争议。

## 2.1.0 - 2021-09-17

### 特性

- Card: 增加 size (small/large/medium) 属性
- List: 新组件
- Input: 增加 warning 图标

### 修复

- Button: 修复 loading 样式
- Other: 修复 IE 11 兼容性

如果你听说过 Keep a Changelog ,它提供的分类方法要复杂得多。

## 1.0.0 - 2022-02-02

### 新增

- List: 新组件
- Input: 增加 warning 图标

### 更改

- Card: large size 的 padding 从 12px 调整为 16px

### 移除

- Card: align 属性,用 headerAlign 和 footerAlign 替代

### 废弃

- Input: focus 属性,建议用 Ref 

### 修复

- Button: 修复 loading 样式
- Other: 修复 IE 11 兼容性

对大部分项目来说,这样做意义不大,会消耗开发者更多的精力。因此建议变更不做细分,或者按照上面特性+修复的简单分类方法。

为什么不用 Git 历史

大多数项目的 Git 历史 commit message 含义不清,很难去阅读。

为什么不用项目管理系统

JIRA 和 AONE 之类的项目管理系统,或者 NPM 这样的软件包平台,确实能够在一定程度上记录软件发布历史。但实际项目中,会出现不得不从一个平台迁移到另一个平台的情况。这些发布记录有时候并不能随代码迁移到新平台。另外,软件分发给客户或者下游之后,他们并不一定能访问我们内部系统的发布历史。