Conventional Commits 與版本發布
概述
提交訊息是一種機器可讀的介面，而非僅僅是散文。自動版本控制與變更日誌生成會解析它們；格式錯誤的訊息會導致錯誤的公開版本或損壞的發布。在小處（一個格式正確的訊息）保持紀律，將自動帶來大處（準確的變更日誌、正確的版本號）的正確性。
格式
<type>(<scope>): <description>
| Type | 效果 / 用途 |
|---|---|
feat | 新功能 — 次要 版本提升 |
fix | 錯誤修正 — 修補 版本提升 |
docs | 僅文件變更 |
chore | 維護、依賴、設定 |
refactor | 保持行為的程式碼變更 |
test | 僅測試 |
ci / build | 管線 / 建置系統變更 |
- 祈使語氣：「add X」，而非「added X」或「adds X」。
- 破壞性變更：
feat!:或BREAKING CHANGE:頁尾 — 觸發 主要 版本提升。 - scope 可選但鼓勵使用：
feat(auth):、fix(db):。
關鍵細節
- 類型↔版本連結意味著打錯
feat或fix會發布錯誤版本。 謹慎選擇類型：「add」= 新功能，「update」= 對現有功能的增強，「fix」= 錯誤。 - 壓縮合併：PR 標題即為最終提交的訊息。 它本身必須是有效的 Conventional Commit，否則發布會出錯。
- 人為撰寫語調。 無 AI/助手歸屬、無
Co-authored-by追蹤、無 generated-by 頁尾。提交讀起來像是由人撰寫的。
常見的合理化藉口
| 藉口 | 現實 |
|---|---|
| 「訊息其實沒那麼重要」 | 它驅動變更日誌和版本號碼。它在機械層面上至關重要。 |
「chore 對這個功能來說已經夠接近了」 | chore 不會提升版本；使用者在發布中不會獲得你的功能。請使用正確的類型。 |
| 「我之後再修正 PR 標題」 | 在壓縮合併時，標題在合併時即為最終版本。請在此之前修正。 |
「Co-authored-by 追蹤是無害的」 | 專案規則禁止 AI 歸屬。沒有例外。 |
紅旗 — 立即停止
- 沒有類型前綴的提交訊息
- 將
chore/docs用於新增或修正使用者可見行為的事項 - 非有效 Conventional Commit 的壓縮 PR 標題
- 任何 AI 歸屬或
Co-authored-by行
強制執行：
- PR 標題 — 在 CI 中驗證，具有阻擋性（
amannn/action-semantic-pull-request）。 由於壓縮合併時標題就是最終發布的提交，因此這是關鍵的把關。 - AI 歸屬 — 一個阻擋性的「無 AI 歸屬」任務會拒絕包含 Claude/Anthropic 的
Co-authored-by追蹤 以及Generated with [Claude…]頁尾，這些都會在分支提交和 PR 主體中檢查（PR 主體會成為壓縮提交的主體）。 人類的Co-authored-by追蹤則不受影響。 - 分支提交主體 — 刻意不進行 lint。壓縮合併會捨棄它們，因此它們永遠不會進入變更日誌。如果你改用合併提交，請加上 commitlint。
已知漏洞： 如果提交是由代理者帳號作者，GitHub 會在壓縮合併時自動組合一個
Co-authored-by 追蹤 — 這是在 PR 檢查執行之後發生。上述把關無法看見它。請勿以代理者身份提交。
完整說明：憲法第三條，收錄於 engineering-constitution/references/engineering-constitution.md。