如何維護更新日誌

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

Version 1.1.0 
# 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

更新日誌是什麼？

更新日誌（Change Log）是一個由人工編輯、以時間為倒序的列表，用於記錄專案中每個版本的顯著改動。

為什麼需要提供更新日誌？

為了讓使用者和開發人員更簡單明確地了解各個版本之間有著哪些顯著改動。

哪些人需要更新日誌？

大家都需要更新日誌。無論是開發人員或是使用者，都會在意軟體包含了什麼東西。當軟件有變動時，大家想知道改了些什麼以及為什麼要改。

怎樣寫出高質量的更新日誌？

撰寫原則

  • 記住日誌是寫給人而非機器的。
  • 每個版本都應該有獨立的入口。
  • 同類改動應該分組放置。
  • 版本與章節應「可連結化」。
  • 新版本在前，舊版本在後。
  • 每個版本都應該註記發佈日期。
  • 版本命名應遵守語義化版本規範。

改動類型

  • Added 當增加了新功能。
  • Changed 當更動了既有的功能。
  • Deprecated 當功能將在近期被移除。
  • Removed 當移除了現有的功能。
  • Fixed 當修復了某些錯誤。
  • Security 當增進了安全性漏洞。

如何提升維護「更新日誌」的效率？

在日誌最上方提供 Unreleased 區塊以記錄即將發佈的更新內容。

這樣做有兩個好處：

  • 讓大家知道在未來的版本中可能會有哪些改動。
  • 在發佈新版本時，直接將 Unreleased 區塊中的內容移動至新發佈版本的描述區塊就可以了。

有很糟糕的更新日誌嗎？

當然有，下麵就是一些糟糕的範例。

🚫 直接複製 git log 到更新日誌

使用 git 日誌作為更新日誌是個非常糟糕的方式：git 日誌充滿各種無意義的信息，如合並提交、語焉不詳的提交標題、文檔更新等。

提交的目的是記錄源碼的演化。一些專案會清理提交記錄，但有些不會。

更新日誌的目的則是記錄重要的改動以供受衆閱讀，通常涵蓋多個提交記錄，最終目的仍然是讓看的人一目了然。

🚫 忽略即將棄用的功能

當從一個版本升級至另一個時，使用者應清楚（盡管痛苦）地知道哪些部分將不再被支援。應該允許先升級至一個列出哪些功能將會被棄用的版本，待去掉那些不再支持的部分後，再升級至把那些棄用功能真正移除的版本。

即使其他什麼都不做，也至少要在更新日誌中列出棄用的、移除的或是任何可能導致程式碼失效的重大改動。

🚫 容易混淆的日期格式

不同區域有著不同的時間格式，要找到讓大家都滿意的日期格式不是件容易的事。使用像2012-06-02 的格式能清楚傳達日期，而且不易與其他日期格式混淆，同時也遵守 ISO 標準。因此，推薦在更新日誌中使用此種日期格式。

🚫 不一致的改動

僅提到部分改動的更新日誌可能和沒有更新日誌一樣危險。 雖然許多改動也許與更新日誌無關——例如，刪除一個空格可能不需要每次都被記錄下來——但任何重要的改動都應該在更新日誌中被提及。 通過不一致地實施改動，使用者可能會錯誤地認為更新日誌是事實的唯一來源（而它也應該是）。 能力越大，責任越大——擁有一個好的更新日誌意味著擁有一個一致性更新的更新日誌。

常見問題

是否有一個標準化的更新日誌格式？

並沒有。雖然有 GNU 更新日誌指南 以及只有兩段長的 GNU - The NEWS File 指南，但這些並不足以稱為「標準」。

此專案旨在提供一個 更好的更新日誌範例，所有點子都來自於對開源社區中優秀實例的觀察與記錄。

歡迎各位提供有建設性的批評、討論及建議。

更新日誌的檔案名稱應該是？

通常使用 CHANGELOG.md。有些專案將其命名為 HISTORY、NEWS 或是 RELEASES。

當然，你可能認為更新日誌的命名並不那麼重要，但為什麼要為難那些僅僅是想看到都有哪些重大改動的使用者呢？

GitHub Releases 怎麼樣？

這是個非常好的提議。GitHub Releases 可通過手動添加發佈日誌或將帶有註釋的 git 標簽信息抓取後轉換的方式，將簡單的 git 標簽（如一個叫 v1.0.0 的標簽）轉換為信息豐富的發佈日誌。

GitHub Releases 產生的日誌只能在 GitHub 上瀏覽，雖然 GitHub Releases 能做出接近本專案範例的日誌格式，但這會增加些許與 GitHub 的相依性。

現行版本的 GitHub Releases 不像那些典型的大寫文件（README，CONTRIBUTING 等），仍可以認為是不利於使用者探索的。另一個小問題則是目前的 GitHub Releases 界麵並沒有提供不同版本間的 commit 日誌的連結。

更新日誌可以被自動識別嗎？

非常睏難，因為有各式各樣的提交訊息和檔案名稱難以完全掌握。

Vandamme 是一個 Ruby 程式，由 Gemnasium 團隊製作，可以解析多種（但絕對不是全部）開源庫的更新日誌。

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

因為重大漏洞或安全性問題而被撤下（unpublished）的版本通常不會出現在更新日誌中，但仍然建議記錄下來。你可以這樣作出記錄：

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

因為這類更改十分重要，所以 [YANKED] 標簽應該非常醒目，讓使用者注意到它是最重要的事。。此外，用方括號包圍可使其更易被程式識別。

可以更改過去版本的日誌內容嗎？

當然可以。總會有合適的原因去改進更新日誌。我也時常提 Pull Request 來為那些未維護更新日誌的開源專案加入缺失的發佈信息。

另外，你很有可能發現自己忘記記錄一個重大功能更新。這種情況下顯然應該重寫更新日誌。

如何貢獻？

本文檔並非真理。而是我經過深思熟慮、遵循蒐集到的資訊和範例之後提出的建議。

源於我期望社群能達到共識，我相信討論的過程與結果一樣重要。

所以歡迎貢獻。

訪談

我在 The Changelog podcast 上講述了為什麼維護者與協作者應該在意更新日誌，以及建立這項專案背後的契機。