如何维护更新日志

参考网址：http://keepachangelog.com/zh-CN/0.3.0/

更新日志绝对不应该是git日志的堆砌物

Version 0.3.0

更新日志是什么？

更新日志（Change Log）是一个由人工编辑，以时间为倒叙的列表。 这个列表记录所有版本的重大变动。

# Change Log
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/)
and this project adheres to [Semantic Versioning](http://semver.org/).

## [Unreleased]
### Added
- zh-CN and zh-TW translations from @tianshuo.
- de translation from @mpbzh.
- it-IT translation from @roalz.
- sv translation from @magol.
- tr-TR translation from @karalamalar.

### Changed
- Start versioning based on the current English version at 0.3.0 to help
translation authors keep things up-to-date.

## [0.3.0] - 2015-12-03
### Added
- RU translation from @aishek.
- pt-BR translation from @tallesl.
- es-ES translation from @ZeliosAriex.

## [0.2.0] - 2015-10-06
### Changed
- Remove exclusionary mentions of "open source" since this project can benefit
both "open" and "closed" source projects equally.

## [0.1.0] - 2015-10-06
### Added
- Answer "Should you ever rewrite a change log?".

### Changed
- Improve argument against commit logs.
- Start following [SemVer](http://semver.org) properly.

## [0.0.8] - 2015-02-17
### Changed
- Update year to match in every README example.
- Reluctantly stop making fun of Brits only, since most of the world
writes dates in a strange way.

### Fixed
- Fix typos in recent README changes.
- Update outdated unreleased diff link.

## [0.0.7] - 2015-02-16
### Added
- Link, and make it obvious that date format is ISO 8601.

### Changed
- Clarified the section on "Is there a standard change log format?".

### Fixed
- Fix Markdown links to tag comparison URL with footnote-style links.

## [0.0.6] - 2014-12-12
### Added
- README section on "yanked" releases.

## [0.0.5] - 2014-08-09
### Added
- Markdown links to version tags on release headings.
- Unreleased section to gather unreleased changes and encourage note
keeping prior to releases.

## [0.0.4] - 2014-08-09
### Added
- Better explanation of the difference between the file ("CHANGELOG")
and its function "the change log".

### Changed
- Refer to a "change log" instead of a "CHANGELOG" throughout the site
to differentiate between the file and the purpose of the file — the
logging of changes.

### Removed
- Remove empty sections from CHANGELOG, they occupy too much space and
create too much noise in the file. People will have to assume that the
missing sections were intentionally left out because they contained no
notable changes.

## [0.0.3] - 2014-08-09
### Added
- "Why should I care?" section mentioning The Changelog podcast.

## [0.0.2] - 2014-07-10
### Added
- Explanation of the recommended reverse chronological release ordering.

## 0.0.1 - 2014-05-31
### Added
- This CHANGELOG file to hopefully serve as an evolving example of a standardized open source project CHANGELOG.
- CNAME file to enable GitHub Pages custom domain
- README now contains answers to common questions about CHANGELOGs
- Good examples and basic guidelines, including proper date formatting.
- Counter-examples: "What makes unicorns cry?"

[Unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...HEAD
[0.3.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.2.0...v0.3.0
[0.2.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.8...v0.1.0
[0.0.8]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.7...v0.0.8
[0.0.7]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.6...v0.0.7
[0.0.6]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.5...v0.0.6
[0.0.5]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.4...v0.0.5
[0.0.4]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.3...v0.0.4
[0.0.3]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.2...v0.0.3
[0.0.2]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.1...v0.0.2

为何要提供更新日志？

为了让用户和开发人员更好知道每一个版本有哪些区别。

为何我要在乎呢？

因为归根结底软件是为人提供的。既然你不关心人，哪么为何写软件呢？ 多少你还是要关心你的受众。

本文档原作者和另外两个人的一个播客向大家介绍了， 为何代码的管理者和开发者应该在乎更新日志。如果你有一小时时间和很好的英文听力本领， 不放听听。

怎么定义好的更新日志

好问题！

一个好的更新日志，一定满足：

• 给人而不是机器写的。记住，要说人话。
• 快速跳转到任意段。所以采用markdown格式
• 一个版本对应一个章节。
• 最新的版本在上，最老的在下面。
• 所有日期采用'YYYY-MM-DD'这种规范。（例如北京奥运会的2008年8月8日是2008-08-08）这个是国际通用，任何语言 都能理解的，并且还被xkcd推荐呢！
• 标出来是否遵守语义化版本格式
• 每一个软件的版本必须：
  • 标明日期（要用上面说过的规范）
  • 标明分类（采用英文）。规范如下：
  • 'Added' 添加的新功能
  • 'Changed' 功能变更
  • 'Deprecated' 不建议使用，未来会删掉
  • 'Removed' 之前不建议使用的功能，这次真的删掉了
  • 'Fixed' 改的bug
  • 'Security' 改的有关安全相关bug

怎么尽可能减少耗费的精力？

永远在文档最上方提供一个'Unreleased' 未发布区域，来记录当前的变化。 这佯作有两大意义。

• 大家可以看到接下来会有什么变化
• 在发布时，只要把'Unreleased'改为当前版本号，然后再添加一个新的'Unreleased'就行了

吐槽环节到了

请你一定要注意：

• 把git日志扔到更新日志里。看似有用，然并卵。
• 不写'deprecations'就删功能。不带这样坑队友的。
• 采用各种不靠谱日期格式 2012年12月12日，也就中国人能看懂了。

如果你还有要吐槽的，欢迎留issue或者直接PR

世界上不是有标准的更新日志格式吗？

貌似GNU或者GNU NEWS还是提过些规范的，事实是它们太过简陋了。 开发有那么多中情况，采用那样的规范，确实是不太合适的。

这个项目提供的规范是作者本人希望能够成为世界规范的。 作者不认为当前的标准足够好，而且作为一个社区，我们是有能力提供更棒的规范。 如果你对这个规范有不满的地方，不要忘记还可以吐槽呢。

更新日志文件名应该叫什么？

我们的案例中给的名字就是最好的规范：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是一个Ruby程序（由Gemnasium团队制作），可以解析 好多种（但绝对不是全部）开源库的更新日志。

到底是CHANGELOG还是更新日志

CHANGELOG是文件名，更新日志是常用说法。CHANGELOG采用大写是有历史根源的。就像很多类似的文件 README， LICENSE，还有CONTRIBUTING。

采用大写可以更加显著，毕竟这是项目很重要的元信息。就像开源徽章。

那些后来撤下的版本怎么办？

因为各种安全/重大bug原因被撤下的版本被标记'YANKED'。这些版本一般不出现在更新日志里，但作者建议他们出现。 显示方式应该是：

## 0.0.5 - 2014-12-13 [YANKED]

[YANKED]采用大写更加显著，因为这个信息很重要。而采用方括号则容易被程序解析。

是否可以重写更新日志

当然。哪怕已经上线了，也可以重新更新更新日志。有许多开源项目更新日志不够新，所以作者就会帮忙更新。

另外，很有可能你忘记记录一个重大功能更新。所以这时候应该去重写更新日志。

如何贡献？

本文档并不是真理。这只是原作者的个人建议，并且包括许多收集的例子。 哪怕本开源库提供一个更新日志案例，我刻意没有提供一个 过于苛刻的规则列表（不像语义化版本格式）。

这是因为我希望通过社区达到统一观点，我认为中间讨论的过程与结果一样重要。

 

所以欢迎贡献。