变更日志 Changelog 的书写方法

2022年 3月 19日代码 changelog

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

最简单的形式

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

# 变更日志

## 未发布

- 修复 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 这样的软件包平台，确实能够在一定程度上记录软件发布历史。但实际项目中，会出现不得不从一个平台迁移到另一个平台的情况。这些发布记录有时候并不能随代码迁移到新平台。另外，软件分发给客户或者下游之后，他们并不一定能访问我们内部系统的发布历史。