mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-08-22 10:18:14 +02:00
Previously they had to be duplicated from the page frontmatter but that's not necessary and also makes it possible to have correct OpenGraph title and descriptions.
147 lines
6.5 KiB
Plaintext
147 lines
6.5 KiB
Plaintext
---
|
||
title: 如何维护更新日志
|
||
description: 更新日志绝对不应该是git日志的堆砌物
|
||
language: zh-CN
|
||
version: 0.3.0
|
||
---
|
||
|
||
%h1= current_page.data.title
|
||
%h2= current_page.data.description
|
||
|
||
Version <strong>#{current_page.metadata[:page][:version]}</strong>
|
||
|
||
:markdown
|
||
### 更新日志是什么?
|
||
更新日志(Change Log)是一个由人工编辑,以时间为倒序的列表。
|
||
这个列表记录所有版本的重大变动。
|
||
|
||
<pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
|
||
|
||
:markdown
|
||
### 为何要提供更新日志?
|
||
为了让用户和开发人员更好知道每一个版本有哪些区别。
|
||
|
||
### 为何我要在乎呢?
|
||
因为归根结底软件是为人提供的。既然你不关心人,那么为何写软件呢?
|
||
多少你还是要关心你的受众。
|
||
|
||
本文档原作者和另外两个人的一个[播客][thechangelog]向大家介绍了,
|
||
为何代码的管理者和开发者应该在乎更新日志。如果你有一小时时间和很好的英文听力本领,
|
||
不妨听听。
|
||
|
||
### 怎么定义好的更新日志
|
||
好问题!
|
||
|
||
一个好的更新日志,一定满足:
|
||
|
||
- 给人而不是机器写的。记住,要说人话。
|
||
- 快速跳转到任意段。所以采用markdown格式
|
||
- 一个版本对应一个章节。
|
||
- 最新的版本在上,最老的在下面。
|
||
- 所有日期采用'YYYY-MM-DD'这种规范。(例如北京奥运会的2008年8月8日是2008-08-08)这个是国际通用,任何语言
|
||
都能理解的,并且还被[xkcd](https://xkcd.com/1179/)推荐呢!
|
||
- 标出来是否遵守[语义化版本格式][semver]
|
||
- 每一个软件的版本必须:
|
||
- 标明日期(要用上面说过的规范)
|
||
- 标明分类(采用英文)。规范如下:
|
||
- 'Added' 添加的新功能
|
||
- 'Changed' 功能变更
|
||
- 'Deprecated' 不建议使用,未来会删掉
|
||
- 'Removed' 之前不建议使用的功能,这次真的删掉了
|
||
- 'Fixed' 改的bug
|
||
- 'Security' 改的有关安全相关bug
|
||
|
||
|
||
### 怎么尽可能减少耗费的精力?
|
||
永远在文档最上方提供一个'Unreleased' 未发布区域,来记录当前的变化。
|
||
这样作有两大意义。
|
||
|
||
- 大家可以看到接下来会有什么变化
|
||
- 在发布时,只要把'Unreleased'改为当前版本号,然后再添加一个新的'Unreleased'就行了
|
||
|
||
|
||
### 吐槽环节到了
|
||
请你一定要注意:
|
||
|
||
- **把git日志扔到更新日志里。**看似有用,然并卵。
|
||
- **不写'deprecations'就删功能。**不带这样坑队友的。
|
||
- **采用各种不靠谱日期格式** 2012年12月12日,也就中国人能看懂了。
|
||
|
||
如果你还有要吐槽的,欢迎留[issue][issues]或者直接PR
|
||
|
||
|
||
### 世界上不是有标准的更新日志格式吗?
|
||
貌似GNU或者GNU NEWS还是提过些规范的,事实是它们太过简陋了。
|
||
开发有那么多种情况,采用那样的规范,确实是不太合适的。
|
||
|
||
这个项目提供的[规范][CHANGELOG]是作者本人希望能够成为世界规范的。
|
||
作者不认为当前的标准足够好,而且作为一个社区,我们是有能力提供更棒的规范。
|
||
如果你对这个规范有不满的地方,不要忘记还可以[吐槽][issues]呢。
|
||
|
||
### 更新日志文件名应该叫什么?
|
||
|
||
我们的案例中给的名字就是最好的规范:`CHANGELOG.md`,注意大小写。
|
||
|
||
像`HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
|
||
`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`这么
|
||
多文件名就太不统一了。
|
||
|
||
只会让大家更难找到。
|
||
|
||
### 为何不直接记录`git log`?
|
||
|
||
因为git日志一定是乱糟糟的。哪怕一个最理想的由完美的程序员开发和提交的,哪怕一个
|
||
从不忘记每次提交全部文件,不写错别字,不忘记重构每一个部分,也无法保证git日志完美无瑕。
|
||
况且git日志的核心在于记录代码的演化,而更新日志则是记录最重要的变更。
|
||
|
||
就像注释之于代码,更新日志之于git日志。前者解释*为什么*,而后者说明*发生了什么*。
|
||
|
||
|
||
### 更新日志能机器识别吗?
|
||
非常困难,因为有各种不同的文件格式和其它规范。
|
||
|
||
[Vandamme][vandamme]是一个Ruby程序(由[Gemnasium][gemnasium]团队制作),可以解析
|
||
好多种(但绝对不是全部)开源库的更新日志。
|
||
|
||
### 到底是CHANGELOG还是更新日志
|
||
|
||
CHANGELOG是文件名,更新日志是常用说法。CHANGELOG采用大写是有历史根源的。就像很多类似的文件
|
||
[`README`][README], [`LICENSE`][LICENSE],还有[`CONTRIBUTING`][CONTRIBUTING]。
|
||
|
||
采用大写可以更加显著,毕竟这是项目很重要的元信息。就像[开源徽章][shields]。
|
||
|
||
### 那些后来撤下的版本怎么办?
|
||
因为各种安全/重大bug原因被撤下的版本被标记'YANKED'。这些版本一般不出现在更新日志里,但作者建议他们出现。
|
||
显示方式应该是:
|
||
|
||
`## [0.0.5] - 2014-12-13 [YANKED]`
|
||
|
||
`[YANKED]`采用大写更加显著,因为这个信息很重要。而采用方括号则容易被程序解析。
|
||
|
||
### 是否可以重写更新日志
|
||
当然。哪怕已经上线了,也可以重新更新更新日志。有许多开源项目更新日志不够新,所以作者就会帮忙更新。
|
||
|
||
另外,很有可能你忘记记录一个重大功能更新。所以这时候应该去重写更新日志。
|
||
|
||
### 如何贡献?
|
||
本文档并不是**真理**。这只是原作者的个人建议,并且包括许多收集的例子。
|
||
哪怕[本开源库][gh]提供一个[更新日志案例][CHANGELOG],我刻意没有提供一个
|
||
过于苛刻的规则列表(不像[语义化版本格式][semver])。
|
||
|
||
这是因为我希望通过社区达到统一观点,我认为中间讨论的过程与结果一样重要。
|
||
|
||
所以[欢迎贡献][gh]。
|
||
|
||
|
||
[CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/main/CHANGELOG.md
|
||
[CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/main/CONTRIBUTING.md
|
||
[LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/main/LICENSE
|
||
[README]: https://github.com/olivierlacan/keep-a-changelog/blob/main/README.md
|
||
[gemnasium]: https://gemnasium.com/
|
||
[gh]: https://github.com/olivierlacan/keep-a-changelog
|
||
[issues]: https://github.com/olivierlacan/keep-a-changelog/issues
|
||
[semver]: https://semver.org/lang/zh-CN/
|
||
[shields]: https://shields.io/
|
||
[thechangelog]: https://changelog.com/podcast/127
|
||
[vandamme]: https://github.com/tech-angels/vandamme/
|