| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149 |
- ---
- description: 如何維護更新日誌
- title: 如何維護更新日誌
- language: zh-TW
- version: 0.3.0
- ---
- :markdown
- # 如何維護更新日誌
- ## 更新日誌絕對不應該是git日誌的堆砌物
- Version **#{current_page.metadata[:page][:version]}**
- ### 更新日誌是什麽？
- 更新日誌（Change Log）是壹個由人工編輯，以時間為倒敘的列表。
- 這個列表記錄所有版本的重大變動。
- %pre.changelog= File.read("CHANGELOG.md")
- :markdown
- ### 為何要提供更新日誌？
- 為了讓用戶和開發人員更好知道每壹個版本有哪些區別。
- ### 為何我要在乎呢？
- 因為歸根結底軟件是為人提供的。既然妳不關心人，哪麽為何寫軟件呢？
- 多少妳還是要關心妳的受眾。
- 本文檔原作者和另外兩個人的壹個[播客][thechangelog]向大家介紹了，
- 為何代碼的管理者和開發者應該在乎更新日誌。如果妳有壹小時時間和很好的英文聽力本領，
- 不放聽聽。
- ### 怎麽定義好的更新日誌
- 好問題！
- 壹個好的更新日誌，壹定滿足：
- - 給人而不是機器寫的。記住，要說人話。
- - 快速跳轉到任意段。所以采用markdown格式
- - 壹個版本對應壹個章節。
- - 最新的版本在上，最老的在下面。
- - 所有日期采用'YYYY-MM-DD'這種規範。（例如北京奧運會的2008年8月8日是2008-08-08）這個是國際通用，任何語言
- 都能理解的，並且還被[xkcd](http://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]。
- 采用大寫可以更加顯著，畢竟這是項目很重要的元信息。就像[開源徽章][shields]。
- ### 那些後來撤下的版本怎麽辦？
- 因為各種安全/重大bug原因被撤下的版本被標記'YANKED'。這些版本壹般不出現在更新日誌裏，但作者建議他們出現。
- 顯示方式應該是：
- `## 0.0.5 - 2014-12-13 [YANKED]`
- `[YANKED]`采用大寫更加顯著，因為這個信息很重要。而采用方括號則容易被程序解析。
- ### 是否可以重寫更新日誌
- 當然。哪怕已經上線了，也可以重新更新更新日誌。有許多開源項目更新日誌不夠新，所以作者就會幫忙更新。
- 另外，很有可能妳忘記記錄壹個重大功能更新。所以這時候應該去重寫更新日誌。
- ### 如何貢獻？
- 本文檔並不是**真理**。這只是原作者的個人建議，並且包括許多收集的例子。
- 哪怕[本開源庫][gh]提供壹個[更新日誌案例][CHANGELOG]，我刻意沒有提供壹個
- 過於苛刻的規則列表（不像[語義化版本格式][semver]）。
- 這是因為我希望通過社區達到統壹觀點，我認為中間討論的過程與結果壹樣重要。
- 所以[歡迎貢獻][gh]。
- [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md
- [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md
- [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE
- [README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md
- [gemnasium]: https://gemnasium.com/
- [gh]: https://github.com/olivierlacan/keep-a-changelog
- [issues]: https://github.com/olivierlacan/keep-a-changelog/issues
- [semver]: http://semver.org/lang/zh-CN/
- [shields]: http://shields.io/
- [thechangelog]: http://5by5.tv/changelog/127
- [vandamme]: https://github.com/tech-angels/vandamme
|
