變更日誌範本

遵循 Keep a Changelog 約定格式的軟體專案變更日誌範本。

# 變更記錄範本：專業專案文件的重要工具 軟體專案的維護不僅僅是編寫程式碼；更是向使用者、貢獻者和未來的自己傳達工作進展的過程。然而，對於許多開發人員來說，更新 CHANGELOG.md 檔案的任務往往被視為事後補救，或是在繁忙的發布過程中被完全遺忘。「變更記錄範本」(Changelog Template) 是一款 Chrome 擴充功能，旨在解決這個問題，為您提供精簡、直觀且專業的工作流程，協助您維護符合業界標準規範的高品質變更記錄。 ## 核心目的：透過「Keep a Changelog」進行更好的溝通 Changelog Template 的核心旨在協助軟體專案遵守「Keep a Changelog」規範。優秀的變更記錄是為專案每個版本精心挑選且按時間順序排列的重要變更清單，而非 git commit 的原始紀錄，它是寫給人類閱讀的文件。 透過使用此擴充功能，您可以確保專案歷史紀錄具備可讀性、條理分明且實用。無論您是在管理小型個人專案、大型開源函式庫，還是一套內部工具，Changelog Template 都能提供您所需的結構，在不增加開發週期負擔的情況下保持透明度與專業性。 ## 您可以信賴的標準格式 此擴充功能嚴格遵循標準變更記錄格式，確保您的文件看起來專業並與更廣泛的生態系統保持相容。您建立的每一項條目都會分類為「Keep a Changelog」專案建議的六種標準變更類型之一： 1. **新增 (Added):** 用於擴展軟體功能的新特性。 2. **變更 (Changed):** 用於改變現有功能運作方式的變更。 3. **棄用 (Deprecated):** 用於即將移除的功能，提醒使用者進行遷移。 4. **移除 (Removed):** 用於已正式從程式碼庫中移除的功能。 5. **修復 (Fixed):** 用於解決問題並提高穩定性的任何錯誤修正。 6. **安全性 (Security):** 用於修復漏洞的關鍵修補程式。 此分類有助於使用者快速瀏覽您的發布說明，找到他們確切需要的資訊，無論是尋找要使用的新工具，還是檢查特定錯誤是否已修正。 ## 編寫有效條目的指導原則 編寫優質的變更記錄是一門藝術，需要在技術準確性與易讀性之間取得平衡。Changelog Template 不僅僅提供一個文字方塊，它還提供了編寫重要條目所需的背景資訊與指導。 我們提倡三個簡單的規則： - **使用單一句子：** 保持簡潔。每個條目一個清晰的重點優於密集的段落。 - **使用過去式：** 您正在描述「已經改變」的內容（例如：使用「改善搜尋效能」而非「改善搜尋效能」）。 - **採用使用者視角：** 為使用您軟體的人編寫，而不是為寫程式碼的人編寫。不要說「重構 SQL 查詢最佳化程式」，而要說「提升搜尋效能 50%」。 該擴充功能甚至能協助處理格式細節，自動將條目首字母大寫，並在您忘記時確保它們以適當的句號結尾。 ## 功能豐富的工作區 Changelog Template 充滿了讓文件撰寫感覺像工作流程中自然一部分的功能： ### 1. 快速建立條目 「建立」(Create) 分頁是您的登陸區域。選擇變更類型，輸入條目，然後點擊「加入至未發布」(Add to Unreleased)。就是這麼簡單。無需再為了寫下快速更新而在 IDE 與 Markdown 檔案之間切換情境。 ### 2. 持久化的「未發布」管理 優秀變更記錄最強大的功能之一是「未發布」(Unreleased) 區域。這作為您自上次正式版本以來所作所有變更的暫存區。Changelog Template 會為您管理此區域，將條目儲存在本機儲存空間，以便您隨時開啟擴充功能時取用。 ### 3. 語意化版本控制 (SemVer) 參考 版本控制不應該是猜謎遊戲。我們的「參考」(Reference) 分頁包含語意化版本控制 (SemVer) 的快速入門指南，協助您決定下一個版本應該是大版本 (Major)、小版本 (Minor) 還是修補版本 (Patch)： - **大版本 (MAJOR):** 用於不相容的 API 變更。 - **小版本 (MINOR):** 用於以向後相容的方式新增功能。 - **修補版本 (PATCH):** 用於向後相容的錯誤修正。 ### 4. 自動化工具參考 對於準備好邁出下一步的團隊，我們提供了業界標準自動化工具的指引，例如 `standard-version`、`release-it` 和 `semantic-release`。這些工具與我們擴充功能產生的 Markdown 格式相輔相成，可自動化您的整個發布流程。 ### 5. 一鍵複製與 Markdown 匯出 當您準備好更新檔案時，只需點擊一下即可將「未發布」區域複製為格式化的 Markdown。需要開啟新專案嗎？使用我們的「完整 CHANGELOG.md 啟動範本」來產生包含必要標頭與連結的完整樣板檔案。 ## 為什麼良好的變更記錄很重要 維護良好的變更記錄不僅僅是一份更新清單；它是一個健康、成熟專案的標誌。它透過向使用者展示專案正積極維護來建立**透明度**。它透過突顯重要的變更來促進**溝通**，否則這些變更可能會埋沒在數百則 commit 訊息中。最重要的是，它展現了**專業性**。當使用者看到乾淨、有組織的 CHANGELOG.md 時，他們知道自己可以信任該專案及其背後的開發人員。 ## 這是為誰準備的？ - **個人開發者：** 保持您的個人專案井井有條，避免「我三個月前做了什麼？」的窘境。 - **小型團隊：** 確保每個人在專案進度上保持同步，而無需為每個微小更新建立複雜的 Jira 看板。 - **開源貢獻者：** 透過提供清晰易讀的發布說明，使您的專案對新使用者更具吸引力。 ## 使用簡易：無需設定，毫無負擔 Changelog Template 的設計理念是讓您在需要使用時才感受到它的存在。無需複雜設定，無需建立外部帳號，也無需管理 API 金鑰。它使用 Chrome 的本機儲存空間來確保您的資料隱私，且僅能在您的機器上存取。UI 極簡且響應迅速，能完美融入您的瀏覽器側邊欄或彈出視窗區域。 別再讓您的專案文件進度落後了。立即開始使用 **Changelog Template**，賦予您的軟體應有的專業歷史紀錄。