mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-08-21 09:48:16 +02:00
bee0534514
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.6 KiB
Plaintext
147 lines
6.6 KiB
Plaintext
---
|
||
title: 如何維護更新日誌
|
||
description: 更新日誌絕對不應該是 git 日誌的堆砌物
|
||
language: zh-TW
|
||
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]。
|
||
|
||
採用大寫可以更加顯著，畢竟這是項目很重要的 metadata。就像[開源徽章][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
|