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