mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-28 16:24:07 +02:00
docs(zh-tw): modify the zh-TW wording (#360)
This commit is contained in:
parent
c818254f06
commit
3062bc823d
@ -20,7 +20,7 @@ version: 1.0.0
|
|||||||
.header
|
.header
|
||||||
.title
|
.title
|
||||||
%h1 如何維護更新日誌
|
%h1 如何維護更新日誌
|
||||||
%h2 更新日誌絕對不應該只是 git log 的堆砌物
|
%h2 別讓你的更新日誌成為 git log 的雙胞胎
|
||||||
|
|
||||||
= link_to changelog do
|
= link_to changelog do
|
||||||
Version
|
Version
|
||||||
@ -34,7 +34,7 @@ version: 1.0.0
|
|||||||
更新日誌是什麼?
|
更新日誌是什麼?
|
||||||
|
|
||||||
%p
|
%p
|
||||||
更新日誌(Changelog)是個記錄專案演進版本間的差異,以時間倒敘、由人工攥寫的列表。
|
更新日誌(Changelog)是說明專案在開發過程中,版本之間的差異紀錄,由開發人員由新而舊撰寫。
|
||||||
|
|
||||||
%h3#why
|
%h3#why
|
||||||
%a.anchor{ href: "#why", aria_hidden: "true" }
|
%a.anchor{ href: "#why", aria_hidden: "true" }
|
||||||
@ -48,7 +48,11 @@ version: 1.0.0
|
|||||||
哪些人需要更新日誌?
|
哪些人需要更新日誌?
|
||||||
|
|
||||||
%p
|
%p
|
||||||
大家都需要更新日誌。無論是使用者還是開發者,軟體最終的用戶都會在意軟體包含了什麼。當軟體更新了,大家會希望知道改了什麼、為什麼要改。
|
大家都需要更新日誌。
|
||||||
|
|
||||||
|
%p
|
||||||
|
無論是開發人員或是使用者,都會在意軟體包含了什麼東西。
|
||||||
|
當軟體更新了,大家都想知道改了些什麼以及為什麼要改。
|
||||||
|
|
||||||
.good-practices
|
.good-practices
|
||||||
%h3#how
|
%h3#how
|
||||||
@ -57,21 +61,21 @@ version: 1.0.0
|
|||||||
|
|
||||||
%h4#principles
|
%h4#principles
|
||||||
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
||||||
指導原則
|
撰寫原則
|
||||||
|
|
||||||
%ul
|
%ul
|
||||||
%li
|
%li
|
||||||
日誌是寫給「人」看的,不是機器。
|
更新日誌是寫給「人」看的,不是機器。
|
||||||
%li
|
%li
|
||||||
每個版本都應該有獨立的進入點。
|
每個版本都應該有獨立的進入點。
|
||||||
%li
|
%li
|
||||||
相同類型的改動應分組放置。
|
相同類型的改動應該被分類在同一組。
|
||||||
%li
|
%li
|
||||||
版本與章節應「可連結化」。
|
版本與章節應「可連結化」。
|
||||||
%li
|
%li
|
||||||
新版本總是寫在前面。
|
新版本總是寫在最前面。
|
||||||
%li
|
%li
|
||||||
每個版本都該註記發佈日期。
|
每個版本都應該註記發佈日期。
|
||||||
%li
|
%li
|
||||||
版本命名應遵守#{link_to "語意化版本", semver}格式。
|
版本命名應遵守#{link_to "語意化版本", semver}格式。
|
||||||
|
|
||||||
@ -81,28 +85,28 @@ version: 1.0.0
|
|||||||
%ul
|
%ul
|
||||||
%li
|
%li
|
||||||
%code Added
|
%code Added
|
||||||
當增加了新功能。
|
:當增加了新功能。
|
||||||
%li
|
%li
|
||||||
%code Changed
|
%code Changed
|
||||||
當更動了既有的功能。
|
:當更動了既有的功能。
|
||||||
%li
|
%li
|
||||||
%code Deprecated
|
%code Deprecated
|
||||||
當功能將在近期被移除。
|
:當功能將在近期被移除。
|
||||||
%li
|
%li
|
||||||
%code Removed
|
%code Removed
|
||||||
當移除了現有的功能。
|
:當移除了現有的功能。
|
||||||
%li
|
%li
|
||||||
%code Fixed
|
%code Fixed
|
||||||
當修復了某些錯誤。
|
:當修復了某些錯誤。
|
||||||
%li
|
%li
|
||||||
%code Security
|
%code Security
|
||||||
當增進了安全性漏洞。
|
:當增進了安全性漏洞。
|
||||||
|
|
||||||
.effort
|
.effort
|
||||||
|
|
||||||
%h3#effort
|
%h3#effort
|
||||||
%a.anchor{ href: "#effort", aria_hidden: "true" }
|
%a.anchor{ href: "#effort", aria_hidden: "true" }
|
||||||
如何提升維護更新日誌的效率?
|
如何提升維護「更新日誌」的效率?
|
||||||
|
|
||||||
%p
|
%p
|
||||||
在日誌上方使用 <code>Unreleased</code> 區塊記錄即將發佈的更新內容。
|
在日誌上方使用 <code>Unreleased</code> 區塊記錄即將發佈的更新內容。
|
||||||
@ -118,41 +122,43 @@ version: 1.0.0
|
|||||||
.bad-practices
|
.bad-practices
|
||||||
%h3#bad-practices
|
%h3#bad-practices
|
||||||
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
||||||
難道日誌能寫得很糟嗎?
|
不就只是個日記而已嗎?難道可以把日誌得很糟嗎?
|
||||||
|
|
||||||
%p 當然。下面有些糟糕的範例:
|
%p 當然,下面有些糟糕的範例:
|
||||||
|
|
||||||
%h4#log-diffs
|
%h4#log-diffs
|
||||||
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
||||||
🚫 直接使用 git log
|
🚫 直接複製 git log 到更新日誌
|
||||||
|
|
||||||
%p
|
%p
|
||||||
使用 git log 作為更新日誌絕對不是個好主意:git log 充滿了各種無意義的訊息,像 merge commits
|
直接把 git log 複製一份成更新日誌絕對不是個好主意。
|
||||||
、亂七八糟的提交訊息、文件更新等。
|
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Commits 的目的應該是記錄原始碼的演化過程。有些項目會清理 commits,有些卻不會。
|
git log 充滿了各種瑣碎的訊息,像 merge commits、亂七八糟的提交訊息或是文件更新等。
|
||||||
|
|
||||||
%p
|
%p
|
||||||
更新日誌的目的則是記錄那些值得一提的改動,經常涵蓋多個 commits,最終目的仍是讓使用者一目了然。
|
Commits 的目的應該是記錄原始碼演進的過程,有些專案會清理 commits,但有些不會。
|
||||||
|
|
||||||
|
%p
|
||||||
|
更新日誌的目的則是記錄那些值得一提的改動,經常涵蓋多個 commits,最終目的仍然是讓看的人一目了然。
|
||||||
|
|
||||||
%h4#ignoring-deprecations
|
%h4#ignoring-deprecations
|
||||||
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
||||||
🚫 忽略 Deprecations
|
🚫 忽略 Deprecations
|
||||||
|
|
||||||
%p
|
%p
|
||||||
當使用者升級版本時,他應該要能預先知道哪些環節可能會出問題。理想的情形下,應該讓使用者有空間能預先升級即將被棄用的功能;待替換掉棄用功能之後,再升級至棄用功能被真正移除的版本。
|
當使用者升級版本時,他應該要能預先知道哪些環節可能會出問題,然而,在理想的狀況下,應該讓使用者有空間能預先升級即將被棄用的功能,替換掉棄用功能之後,再升級至棄用功能被真正移除的版本。
|
||||||
|
|
||||||
%p
|
%p
|
||||||
即使不這麼做,也要在更新日誌中列出棄用的、移除的、或是任何可能導致程式碼失效的重大改動。
|
即使不這麼做,也要在更新日誌中列出棄用的、移除的或是任何可能導致程式碼失效的重大改動。
|
||||||
|
|
||||||
%h4#confusing-dates
|
%h4#confusing-dates
|
||||||
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
||||||
🚫 易混淆的日期格式
|
🚫 容易混淆的日期格式
|
||||||
|
|
||||||
%p
|
%p
|
||||||
在世界的每個角落,不同區域有著不同的時間格式,找到讓大家都滿意的日期格式不是件簡單的事。使用像
|
在世界的每個角落,不同區域有著不同的時間格式,找到讓大家都滿意的日期格式不是件簡單的事。使用像
|
||||||
<code>2017-07-17</code> 的格式能清楚傳達日期、不易與其他日期格式混淆,同時也遵守
|
<code>2017-07-17</code> 的格式能清楚傳達日期,而且不易與其他日期格式混淆,同時也遵守
|
||||||
#{link_to "ISO 標準", iso},因此推薦使用像這樣的日期格式。
|
#{link_to "ISO 標準", iso},因此推薦使用像這樣的日期格式。
|
||||||
|
|
||||||
%aside
|
%aside
|
||||||
|
Loading…
x
Reference in New Issue
Block a user