變更日誌慣例

變更日誌慣例

本頁是每個公開 NextPDF 儲存庫在記錄變更與發布版本時遵循的契約。它是慣例的參考依據；並不對任何套件行為做出主張。各套件、各版本的敘述內容存放在各自儲存庫的 CHANGELOG.md 中。本頁定義它們共用的規則，讓跨儲存庫變更日誌的摘要保持一致，且不會洩漏資訊。

Conventional Commits 1.0.0

每個 commit 的標題都採 type(scope): description 格式。其中 type 是下列其中之一：

類型	意義	使用者可見	版本影響
feat	新功能	是	提升次版本號
fix	行為修正	是	提升修補版本號
perf	效能改善，且不改變行為	是	提升修補版本號
refactor	內部結構調整，無可觀察的變更	否	無
docs	僅文件變更	否	無
test	僅測試變更	否	無
build / ci	僅建置或管線變更	否	無
chore	維護、相依套件、工具鏈	否	無
revert	還原先前的 commit	視情況而定	視情況而定

破壞性變更會在類型或範圍後加上 ! 標記（feat(api)!: …），或以 BREAKING CHANGE: 註腳標記。在 Semantic Versioning 下，兩者都會提升主版本號。與安全性相關的修正會被記錄下來，便於篩選進跨儲存庫摘要的 Security 欄位。

Semantic Versioning 2.0.0

版本號提升是機械化判定。凡是包含任何破壞性變更的版本發布，即為主版本。否則，凡是包含任何 feat 的版本發布，即為次版本。否則，凡是包含任何 fix 或 perf 的版本發布，即為修補版本。依據 SemVer §4，1.0 之前的套件可因破壞性變更提升次版本號。該 commit 仍會帶有破壞性標記，讓摘要保持準確。

Keep a Changelog 分組

每個儲存庫的 CHANGELOG.md 都遵循 Keep a Changelog 1.1.0：項目會依各發布版本分組於 Added、Changed、Deprecated、Removed、Fixed，以及 Security 之下。[Unreleased] 區段可在儲存庫中保留進行中的記錄，但跨儲存庫摘要只會計入已打標籤、已發布的版本。尚未發布的工作絕不會出現在公開索引中。

跨儲存庫摘要如何推導（並保持不洩漏）

變更日誌索引上的摘要表，是以唯讀方式讀取每個儲存庫在其最新發布標籤處的 Conventional Commits 歷史，並統計各類別後產生。這些推導規則刻意收斂在很窄的範圍內，以避免任何內部細節外洩：

1. 只計數量，不含內容。 只會回報每種使用者可見類型的 commit 數量。不會呈現任何 commit 的標題、內文、註腳或雜湊值。
2. 僅限使用者可見的類型。 docs、test、ci、chore，以及 refactor 都會被排除；它們不會改變套件使用者所能觀察到的任何內容。
3. 僅限已發布。 commit 只有在成為某個公開套件已打標籤發布版本的一部分後才會被計入。
4. 不含識別碼。 可能出現在私有 commit 範圍中的內部 issue、ticket、cycle、wave 或工作項目參照絕不會被揭露，因為範圍文字本身永遠不會被呈現；只會讀取類型。
5. 不含自動化署名。 不會讀取或顯示自動產生的貢獻者尾註。

這就是為什麼公開變更日誌是類別摘要，再加上連往各套件自身 CHANGELOG.md 的連結，而非彙整後的 commit 資訊流。就構造而言，這份摘要可被證明不含任何內部洩漏。權威性的敘述內容會保留在擁有它的套件中。

另請參閱

• 變更日誌
• 整合範例慣例
• Conventional Commits 1.0.0
• Semantic Versioning 2.0.0