mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-29 16:54:12 +02:00
Fixed typos and improved the translation in Traditional Chinese (zh-TW)
This commit is contained in:
Jian Zi-yao
parent
8404168d28
commit
ec4c96c6b7
@ -8,12 +8,12 @@ version: 0.3.0
|
||||
:markdown
|
||||
# 如何維護更新日誌
|
||||
|
||||
## 更新日誌絕對不應該是git日誌的堆砌物
|
||||
## 更新日誌絕對不應該是 git 日誌的堆砌物
|
||||
|
||||
Version **#{current_page.metadata[:page][:version]}**
|
||||
|
||||
### 更新日誌是什麽？
|
||||
更新日誌（Change Log）是壹個由人工編輯，以時間為倒敘的列表。
|
||||
更新日誌（Change Log）是一個由人工編輯，以時間為倒敘的列表。
|
||||
這個列表記錄所有版本的重大變動。
|
||||
|
||||
|
||||
@ -21,116 +21,116 @@ version: 0.3.0
|
||||
|
||||
:markdown
|
||||
### 為何要提供更新日誌？
|
||||
為了讓用戶和開發人員更好知道每壹個版本有哪些區別。
|
||||
為了讓用戶和開發人員更好知道每一個版本有哪些區別。
|
||||
|
||||
### 為何我要在乎呢？
|
||||
因為歸根結底軟件是為人提供的。既然妳不關心人，哪麽為何寫軟件呢？
|
||||
多少妳還是要關心妳的受眾。
|
||||
因為歸根結底軟體是為人提供的。既然你不關心人，那麽為何寫軟體呢？
|
||||
多少你還是要關心你的受眾。
|
||||
|
||||
本文檔原作者和另外兩個人的壹個[播客][thechangelog]向大家介紹了，
|
||||
為何代碼的管理者和開發者應該在乎更新日誌。如果妳有壹小時時間和很好的英文聽力本領，
|
||||
不放聽聽。
|
||||
本文檔原作者和另外兩個人的一個[部落格][thechangelog]向大家介紹了，
|
||||
為何程式碼的管理者和開發者應該在乎更新日誌。如果你有一小時時間和很好的英文聽力本領，
|
||||
不妨聽聽。
|
||||
|
||||
### 怎麽定義好的更新日誌
|
||||
好問題！
|
||||
|
||||
壹個好的更新日誌，壹定滿足：
|
||||
一個好的更新日誌，一定滿足：
|
||||
|
||||
- 給人而不是機器寫的。記住，要說人話。
|
||||
- 快速跳轉到任意段。所以采用markdown格式
|
||||
- 壹個版本對應壹個章節。
|
||||
- 最新的版本在上，最老的在下面。
|
||||
- 所有日期采用'YYYY-MM-DD'這種規範。（例如北京奧運會的2008年8月8日是2008-08-08）這個是國際通用，任何語言
|
||||
都能理解的，並且還被[xkcd](http://xkcd.com/1179/)推薦呢！
|
||||
- 快速跳轉到任意段。所以採用 markdown 格式
|
||||
- 一個版本對應一個章節。
|
||||
- 最新的版本在上面，最舊的在下面。
|
||||
- 所有日期採用 'YYYY-MM-DD' 這種規範。（例如北京奧運會的 2008 年 8 月 8 日是 2008-08-08）這個是國際通用，任何語言
|
||||
都能理解的，並且還被 [xkcd](http://xkcd.com/1179/) 推薦呢！
|
||||
- 標出來是否遵守[語義化版本格式][semver]
|
||||
- 每壹個軟件的版本必須：
|
||||
- 每一個軟體的版本必須：
|
||||
- 標明日期（要用上面說過的規範）
|
||||
- 標明分類（采用英文）。規範如下：
|
||||
- 標明分類（採用英文）。規範如下：
|
||||
- 'Added' 添加的新功能
|
||||
- 'Changed' 功能變更
|
||||
- 'Deprecated' 不建議使用，未來會刪掉
|
||||
- 'Removed' 之前不建議使用的功能，這次真的刪掉了
|
||||
- 'Fixed' 改的bug
|
||||
- 'Security' 改的有關安全相關bug
|
||||
- 'Fixed' 修正的 bug
|
||||
- 'Security' 修正了安全相關的 bug
|
||||
|
||||
|
||||
### 怎麽盡可能減少耗費的精力？
|
||||
永遠在文檔最上方提供壹個'Unreleased' 未發布區域，來記錄當前的變化。
|
||||
這佯作有兩大意義。
|
||||
永遠在文檔最上方提供一個 'Unreleased' 未發布區域，來記錄當前的變化。
|
||||
這樣做有兩大意義。
|
||||
|
||||
- 大家可以看到接下來會有什麽變化
|
||||
- 在發布時，只要把'Unreleased'改為當前版本號，然後再添加壹個新的'Unreleased'就行了
|
||||
- 在發布時，只要把 'Unreleased' 改為當前版本號，然後再添加一個新的 'Unreleased' 就行了
|
||||
|
||||
|
||||
### 吐槽環節到了
|
||||
請妳壹定要註意：
|
||||
請你一定要注意：
|
||||
|
||||
- **把git日誌扔到更新日誌裏。**看似有用，然並卵。
|
||||
- **不寫'deprecations'就刪功能。**不帶這樣坑隊友的。
|
||||
- **采用各種不靠譜日期格式** 2012年12月12日，也就中國人能看懂了。
|
||||
- **把 git 日誌扔到更新日誌裏。**看似有用，然而並沒有什麼作用。
|
||||
- **不寫 'deprecations' 就刪功能。**不帶這樣坑隊友的。
|
||||
- **採用各種不可靠的日期格式** 2012 年 12 月 12 日，也就懂中文的人能看得懂了。
|
||||
|
||||
如果妳還有要吐槽的，歡迎留[issue][issues]或者直接PR
|
||||
如果你還有要吐槽的，歡迎留 [issue][issues] 或者直接 PR
|
||||
|
||||
|
||||
### 世界上不是有標準的更新日誌格式嗎？
|
||||
貌似GNU或者GNU NEWS還是提過些規範的，事實是它們太過簡陋了。
|
||||
開發有那麽多中情況，采用那樣的規範，確實是不太合適的。
|
||||
貌似 GNU 或者 GNU NEWS 還是提過些規範的，事實是它們太過簡陋了。
|
||||
開發有那麽多中情況，採用那樣的規範，確實是不太合適的。
|
||||
|
||||
這個項目提供的[規範][CHANGELOG]是作者本人希望能夠成為世界規範的。
|
||||
作者不認為當前的標準足夠好，而且作為壹個社區，我們是有能力提供更棒的規範。
|
||||
如果妳對這個規範有不滿的地方，不要忘記還可以[吐槽][issues]呢。
|
||||
作者不認為當前的標準足夠好，而且作為一個社區，我們是有能力提供更棒的規範。
|
||||
如果你對這個規範有不滿的地方，不要忘記還可以[吐槽][issues]呢。
|
||||
|
||||
### 更新日誌文件名應該叫什麽？
|
||||
|
||||
我們的案例中給的名字就是最好的規範：`CHANGELOG.md`，註意大小寫。
|
||||
我們的案例中給的名字就是最好的規範：`CHANGELOG.md`，注意大小寫。
|
||||
|
||||
像`HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
|
||||
`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`這麽
|
||||
多文件名就太不統壹了。
|
||||
像 `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
|
||||
`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md` 這麽
|
||||
多文件名就太不統一了。
|
||||
|
||||
只會讓大家更難找到。
|
||||
|
||||
### 為何不直接記錄`git log`?
|
||||
### 為何不直接記錄 `git log`?
|
||||
|
||||
因為git日誌壹定是亂糟糟的。哪怕壹個最理想的由完美的程序員開發的提交的，哪怕壹個
|
||||
從不忘記每次提交全部文件，不寫錯別字，不忘記重構每壹個部分——也無法保證git日誌完美無瑕。
|
||||
況且git日誌的核心在於記錄代碼的演化，而更新日誌則是記錄最重要的變更。
|
||||
因為 git 日誌一定是亂糟糟的。哪怕一個最理想的由完美的程序員開發的提交的，哪怕一個
|
||||
從不忘記每次提交全部文件，不寫錯別字，不忘記重構每一個部分——也無法保證 git 日誌完美無瑕。
|
||||
況且 git 日誌的核心在於記錄代碼的演化，而更新日誌則是記錄最重要的變更。
|
||||
|
||||
就像註釋之於代碼，更新日誌之於git日誌。前者解釋*為什麽*，而後者說明*發生了什麽*。
|
||||
就像註解之於程式碼，更新日誌之於 git 日誌。前者解釋*為什麽*，而後者說明*發生了什麽*。
|
||||
|
||||
|
||||
### 更新日誌能機器識別嗎？
|
||||
非常困難，因為有各種不同的文件格式和其他規範。
|
||||
|
||||
[Vandamme][vandamme]是壹個Ruby程序（由[Gemnasium][gemnasium]團隊制作），可以解析
|
||||
好多種（但絕對不是全部）開源庫的更新日誌。
|
||||
[Vandamme][vandamme] 是一支 Ruby 程式（由 [Gemnasium][gemnasium] 團隊制作），可以解析
|
||||
很多種（但絕對不是全部）開源程式庫的更新日誌。
|
||||
|
||||
### 到底是CHANGELOG還是更新日誌
|
||||
### 到底是 CHANGELOG 還是更新日誌
|
||||
|
||||
CHANGELOG是文件名，更新日誌是常用說法。CHANGELOG采用大寫是有歷史根源的。就像很多類似的文件
|
||||
[`README`][README]， [`LICENSE`][LICENSE]，還有[`CONTRIBUTING`][CONTRIBUTING]。
|
||||
CHANGELOG 是文件名，更新日誌是常用說法。CHANGELOG 採用大寫是有歷史根源的。就像很多類似的文件
|
||||
[`README`][README]，[`LICENSE`][LICENSE]，還有 [`CONTRIBUTING`][CONTRIBUTING]。
|
||||
|
||||
采用大寫可以更加顯著，畢竟這是項目很重要的元信息。就像[開源徽章][shields]。
|
||||
採用大寫可以更加顯著，畢竟這是項目很重要的 metadata。就像[開源徽章][shields]。
|
||||
|
||||
### 那些後來撤下的版本怎麽辦？
|
||||
因為各種安全/重大bug原因被撤下的版本被標記'YANKED'。這些版本壹般不出現在更新日誌裏，但作者建議他們出現。
|
||||
因為各種安全/重大 bug 原因被撤下的版本被標記 'YANKED'。這些版本一般不出現在更新日誌裏，但作者建議他們出現。
|
||||
顯示方式應該是：
|
||||
|
||||
`## 0.0.5 - 2014-12-13 [YANKED]`
|
||||
|
||||
`[YANKED]`采用大寫更加顯著，因為這個信息很重要。而采用方括號則容易被程序解析。
|
||||
`[YANKED]` 採用大寫更加顯著，因為這個訊息很重要。而採用方括號則容易被程式解析。
|
||||
|
||||
### 是否可以重寫更新日誌
|
||||
當然。哪怕已經上線了，也可以重新更新更新日誌。有許多開源項目更新日誌不夠新，所以作者就會幫忙更新。
|
||||
|
||||
另外，很有可能妳忘記記錄壹個重大功能更新。所以這時候應該去重寫更新日誌。
|
||||
另外，很有可能你忘記記錄一個重大功能更新。所以這時候應該去重寫更新日誌。
|
||||
|
||||
### 如何貢獻？
|
||||
本文檔並不是**真理**。這只是原作者的個人建議，並且包括許多收集的例子。
|
||||
哪怕[本開源庫][gh]提供壹個[更新日誌案例][CHANGELOG]，我刻意沒有提供壹個
|
||||
哪怕[本開源庫][gh]提供一個[更新日誌案例][CHANGELOG]，我刻意沒有提供一個
|
||||
過於苛刻的規則列表（不像[語義化版本格式][semver]）。
|
||||
|
||||
這是因為我希望通過社區達到統壹觀點，我認為中間討論的過程與結果壹樣重要。
|
||||
這是因為我希望通過社區達到統一觀點，我認為中間討論的過程與結果一樣重要。
|
||||
|
||||
所以[歡迎貢獻][gh]。
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user