There is a newer version available: 正體中文 1.1.0

如何維護更新日誌

更新日誌絕對不應該是 git 日誌的堆砌物

Version 0.3.0

更新日誌是什麽？

更新日誌（Change Log）是一個由人工編輯，以時間為倒敘的列表。這個列表記錄所有版本的重大變動。

# Changelog

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

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- v1.1 Brazilian Portuguese translation.
- v1.1 German Translation
- v1.1 Spanish translation.
- v1.1 Italian translation.
- v1.1 Polish translation.
- v1.1 Ukrainian translation.

### Changed

- Use frontmatter title & description in each language version template
- Replace broken OpenGraph image with an appropriately-sized Keep a Changelog 
  image that will render properly (although in English for all languages)
- Fix OpenGraph title & description for all languages so the title and 
description when links are shared are language-appropriate

### Removed

- Trademark sign previously shown after the project description in version 
0.3.0

## [1.1.1] - 2023-03-05

### Added

- Arabic translation (#444).
- v1.1 French translation.
- v1.1 Dutch translation (#371).
- v1.1 Russian translation (#410).
- v1.1 Japanese translation (#363).
- v1.1 Norwegian Bokmål translation (#383).
- v1.1 "Inconsistent Changes" Turkish translation (#347).
- Default to most recent versions available for each languages.
- Display count of available translations (26 to date!).
- Centralize all links into `/data/links.json` so they can be updated easily.

### Fixed

- Improve French translation (#377).
- Improve id-ID translation (#416).
- Improve Persian translation (#457).
- Improve Russian translation (#408).
- Improve Swedish title (#419).
- Improve zh-CN translation (#359).
- Improve French translation (#357).
- Improve zh-TW translation (#360, #355).
- Improve Spanish (es-ES) transltion (#362).
- Foldout menu in Dutch translation (#371).
- Missing periods at the end of each change (#451).
- Fix missing logo in 1.1 pages.
- Display notice when translation isn't for most recent version.
- Various broken links, page versions, and indentations.

### Changed

- Upgrade dependencies: Ruby 3.2.1, Middleman, etc.

### Removed

- Unused normalize.css file.
- Identical links assigned in each translation file.
- Duplicate index file for the english version.

## [1.1.0] - 2019-02-15

### Added

- Danish translation (#297).
- Georgian translation from (#337).
- Changelog inconsistency section in Bad Practices.

### Fixed

- Italian translation (#332).
- Indonesian translation (#336).

## [1.0.0] - 2017-06-20

### Added

- New visual identity by [@tylerfortune8](https://github.com/tylerfortune8).
- Version navigation.
- Links to latest released version in previous versions.
- "Why keep a changelog?" section.
- "Who needs a changelog?" section.
- "How do I make a changelog?" section.
- "Frequently Asked Questions" section.
- New "Guiding Principles" sub-section to "How do I make a changelog?".
- Simplified and Traditional Chinese translations from [@tianshuo](https://github.com/tianshuo).
- German translation from [@mpbzh](https://github.com/mpbzh) & [@Art4](https://github.com/Art4).
- Italian translation from [@azkidenz](https://github.com/azkidenz).
- Swedish translation from [@magol](https://github.com/magol).
- Turkish translation from [@emreerkan](https://github.com/emreerkan).
- French translation from [@zapashcanon](https://github.com/zapashcanon).
- Brazilian Portuguese translation from [@Webysther](https://github.com/Webysther).
- Polish translation from [@amielucha](https://github.com/amielucha) & [@m-aciek](https://github.com/m-aciek).
- Russian translation from [@aishek](https://github.com/aishek).
- Czech translation from [@h4vry](https://github.com/h4vry).
- Slovak translation from [@jkostolansky](https://github.com/jkostolansky).
- Korean translation from [@pierceh89](https://github.com/pierceh89).
- Croatian translation from [@porx](https://github.com/porx).
- Persian translation from [@Hameds](https://github.com/Hameds).
- Ukrainian translation from [@osadchyi-s](https://github.com/osadchyi-s).

### Changed

- Start using "changelog" over "change log" since it's the common usage.
- Start versioning based on the current English version at 0.3.0 to help
  translation authors keep things up-to-date.
- Rewrite "What makes unicorns cry?" section.
- Rewrite "Ignoring Deprecations" sub-section to clarify the ideal
  scenario.
- Improve "Commit log diffs" sub-section to further argument against
  them.
- Merge "Why can’t people just use a git log diff?" with "Commit log
  diffs".
- Fix typos in Simplified Chinese and Traditional Chinese translations.
- Fix typos in Brazilian Portuguese translation.
- Fix typos in Turkish translation.
- Fix typos in Czech translation.
- Fix typos in Swedish translation.
- Improve phrasing in French translation.
- Fix phrasing and spelling in German translation.

### Removed

- Section about "changelog" vs "CHANGELOG".

## [0.3.0] - 2015-12-03

### Added

- RU translation from [@aishek](https://github.com/aishek).
- pt-BR translation from [@tallesl](https://github.com/tallesl).
- es-ES translation from [@ZeliosAriex](https://github.com/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](https://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/v1.1.1...HEAD
[1.1.1]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.1.0...v1.1.1
[1.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...v1.0.0
[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
[0.0.1]: https://github.com/olivierlacan/keep-a-changelog/releases/tag/v0.0.1

為何要提供更新日誌？

為了讓用戶和開發人員更好知道每一個版本有哪些區別。

為何我要在乎呢？

因為歸根結底軟體是為人提供的。既然你不關心人，那麽為何寫軟體呢？多少你還是要關心你的受眾。

本文檔原作者和另外兩個人的一個部落格向大家介紹了，為何程式碼的管理者和開發者應該在乎更新日誌。如果你有一小時時間和很好的英文聽力本領，不妨聽聽。

怎麽定義好的更新日誌

好問題！

一個好的更新日誌，一定滿足：

給人而不是機器寫的。記住，要說人話。
快速跳轉到任意段。所以採用 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。

採用大寫可以更加顯著，畢竟這是項目很重要的 metadata。就像開源徽章。

那些後來撤下的版本怎麽辦？

因為各種安全/重大 bug 原因被撤下的版本被標記 'YANKED'。這些版本一般不出現在更新日誌裏，但作者建議他們出現。顯示方式應該是：

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

[YANKED] 採用大寫更加顯著，因為這個訊息很重要。而採用方括號則容易被程式解析。

是否可以重寫更新日誌

當然。哪怕已經上線了，也可以重新更新更新日誌。有許多開源項目更新日誌不夠新，所以作者就會幫忙更新。

另外，很有可能你忘記記錄一個重大功能更新。所以這時候應該去重寫更新日誌。

如何貢獻？

本文檔並不是真理。這只是原作者的個人建議，並且包括許多收集的例子。哪怕本開源庫提供一個更新日誌案例，我刻意沒有提供一個過於苛刻的規則列表（不像語義化版本格式）。

這是因為我希望通過社區達到統一觀點，我認為中間討論的過程與結果一樣重要。

所以歡迎貢獻。