語意版本的自動化,本質上是把「下一版該發多少」交給 commit 訊息決定。依照 Conventional Commits 的對應,feat 會發 minor,fix 發 patch,帶 BREAKING CHANGE: 的 commit 發 major;semantic-release 的 commit analyzer 讀的也是訊息本身,不看這筆 commit 改了哪些檔案。
這套做法建立在一個前提上:寫 commit 的人理解每個類型在版號上的後果。現在 commit 越來越常由 coding agent 撰寫,前提就鬆動了。代理寫下 feat,可能只是覺得這次「加了東西」;在 monorepo 裡修好文件網站的一個錯誤寫成 fix(site),分析器照樣把它算成套件的 patch;替一段重構補上 BREAKING CHANGE: 註腳,下一次合併就會直接發出 major。規則本身都沒有被違反,版本卻已經不是維護者想發的版本。
另一個前提則落在工具上。常見的組合是 semantic-release 負責發版、commitlint 負責檢查 commit,再加上 changelog preset 產生 release notes。三個工具各有設定格式,同一套類型規則要分別寫進 release.config.js、commitlint.config.js 與 preset 裡;規則改了,得同時確認它在檢查、版本分析與 release notes 三處的效果一致。對代理來說,規則散在設定檔與外掛之間,也很難從單一位置讀到「這個類型會發什麼版」。
aronrepo 是我為這個問題做的工具:讓代理和維護者照著同一份規則工作,並由規則擋下會誤發的 commit,不靠代理自己判斷。
一個套件,一套固定的規則
aronrepo 把 commit 檢查、版本規劃、release notes、npm 發佈與 GitHub Release 收進同一個套件,不需要另外安裝 semantic-release、commitlint 或 conventional-changelog。
要在自己的專案使用,可以前往 aronrepo GitHub 專案,複製 README「AI Coding Integration」中的安裝提示,貼給 coding agent,讓它依專案環境完成導入。
這套設計做了幾個取捨。
類型固定,每個類型只有一個意思
專案不能新增或改名 commit 類型。Feat 是新能力,Improve 是改善既有能力,Fix 是已發佈行為的錯誤修正,Upgrade 是執行期依賴的變更,Chore 是維護工作;Docs、Test、Build、CI 等類型不發版。類型不在清單內、或摘要結尾帶句號的 commit,aronrepo check 會拒絕並提示合格的標題。類型與 scope 不分大小寫,fix(core): repair cache 和 Fix(Core): Repair cache 是同一筆 commit,release notes 會把句首轉成大寫;從 Conventional Commits 遷移的專案,多數 commit 可以照原本的寫法。
固定類型犧牲了各專案的自訂空間。我接受這個代價,因為類型一旦可以自訂,代理就得先讀懂每個專案的方言;固定之後,它只要判斷這次改動屬於哪一類,版本層級由規則決定。
minor 與 major 由擁有者決定
預設的 explicit 模式下,除了 Bump(Minor) 與 Bump(Major),所有類型最多只發 patch,BREAKING CHANGE: 註腳會被拒絕。換句話說,代理寫 Feat 頂多發一個 patch,要發 minor 或 major,必須有一筆明確的 Bump commit。需要 Conventional Commits 行為的專案可以改用 auto 模式,讓 Feat 發 minor、破壞性註腳發 major。
兩種模式的差別,在於版號對使用者代表什麼。

explicit 適合把 minor 與 major 當成對外發布的專案,例如有公開遷移指南的框架、設計系統或 UI 元件庫。這類專案的 major 通常伴隨遷移文件、公告與相容期,minor 可能對應一次版本說明或文件改版,時間點由擁有者安排。日常合併的功能與修正以 patch 持續發出,累積到準備對外說明時,再推一筆 Bump(Minor)。Bump 不受發布路徑檢查限制,可以是一筆空 commit,例如 git commit --allow-empty -m "Bump(Minor): Release the new theme API"。代價是新功能會先以 patch 出現:用 ~ 範圍鎖定 patch 的使用者也會收到新增的 API,依語意版本的嚴格定義,這應該是 minor。
auto 適合版號主要給工具與相依範圍讀、而不是給人看的專案,例如團隊內部共用的套件、由自家應用程式消費的 SDK,或功能單純的 CLI 與 utility。使用者靠 ^ 範圍自動升級,需要版號精確反映「有沒有新 API、有沒有破壞相容」,而不需要有人替每個 minor 安排時間點。這時 commit 類型與 BREAKING CHANGE: 註腳會直接變成版號,PR 審查就必須把 commit 標題與註腳也看進去;CI 中的 aronrepo check --title 能擋下格式錯誤,卻無法判斷一項改動是否真的破壞相容。
模式本身也是擁有者的決定。aronrepo 給代理的規則寫明:導入時必須詢問擁有者要用哪一種模式;在已導入的專案中,除非使用者在當次對話要求,代理不能寫 Bump(Major)、Bump(Minor) 或破壞性標記。
沒改到發佈檔案的 commit 不發版
aronrepo 用發布路徑判斷一筆 commit 有沒有碰到會發佈的內容。預設是公開 workspace 套件的目錄,排除測試、fixture、benchmark、範例與 changelog 等。發版類型的 commit 如果沒有改到任何發布路徑,aronrepo check 會在合併前拒絕,也不會發版。前面提到的 Fix(Site),就會被要求改成不發版的類型。

每個決定都說得出理由
aronrepo explain 會列出下一個版本,以及每筆 commit 為什麼發或不發;aronrepo release 發版時也記錄同樣的判斷,--dry-run 則只印出計畫與 release notes。代理在推送到發版分支前可以先跑 explain,維護者審 PR 時看的也是同一份結論。explain --json 另外輸出要發的 commit(head)與完整的 release notes,CI 可以把它放進摘要,讓審核的就是實際會發出的內容。
中斷的發版可以接著完成
monorepo 的發版常常在中途失敗:部分套件已經上了 npm,tag 卻還沒推。aronrepo release 先把所有套件發佈到暫存的 dist-tag,確認 registry 都能取得後才移動正式的 dist-tag,接著推 tag、建立 GitHub Release。重跑同一個 job 時,已從同一個 commit 發佈的版本會略過,缺少的 tag 或 release 會補上。版本號只從 vX.Y.Z tag 讀取,不會把版本寫回 package.json 再 commit。
什麼時候發,可以交給維護者
推送就發版只是預設的 CI 寫法。有固定上線週期的專案,常希望 PR 持續合併到 main、測試環境照常部署,正式版則等維護者決定時間。這類需求不必另開 release 分支,也不需要 Release PR:aronrepo 的版本是從上一個 tag 算到要發的那個 commit,週一到週四合併的四筆 Fix,週五才發時仍然是一個 patch,release notes 一次列出四筆。
要改的是觸發方式。main 每次推送只執行 explain --json,把版本、commit 與 release notes 寫進 job 摘要;正式發版改成手動觸發的 workflow,輸入預覽中的 commit 與版本,並掛上設定 required reviewers 的 GitHub Environment,批准留在 GitHub 的部署紀錄裡。發版步驟執行:
aronrepo release --branch main --expect 1.2.4release 會先確認簽出的 commit 確實在 origin/main 上,避免把 feature 分支的 commit 當成 main 發佈;--expect 則在發版當下重新計算,版本和批准時看到的不同就停下,不會發佈任何東西。下一次發版從這個 tag 接著算,批准之後才合併的 commit 留到下一版。完整的 workflow 範例在 aronrepo 的 README。
給代理的不是文件,是資料
只把規則寫進 README,代理仍然需要讀懂並記住。aronrepo 讓同一份政策有三個出口:
aronrepo policy --json輸出目前專案的模式、發布路徑、每個類型的發版層級與說明。aronrepo agents --write把政策區塊寫進AGENTS.md,指令依專案的套件管理器產生;區塊過期時,aronrepo agents與aronrepo doctor會失敗,沒有人需要手動複製類型表。aronrepo check在 commit-msg hook、PR 的每筆 commit 與 PR 標題上執行同一套檢查。標題不合格時,它會印出建議的寫法。
README 也附了一段可以直接貼給 coding agent 的導入提示:先檢查專案、詢問擁有者要用哪種模式、移除 semantic-release 與 commitlint、加上 hook 與 CI,最後跑 doctor、explain 與 release --dry-run 回報下一個版本。導入工作本身則使用 Build、CI、Chore(Agent) 這類不發版的類型。
和 semantic-release、release-please、changesets 比較
JavaScript 專案常見的發版工具還有兩種做法。release-please 同樣讀 Conventional Commits,但不直接發版,而是維護一個 Release PR,合併時才建立 tag 與 GitHub Release;changesets 則完全不看 commit 訊息,由開發者在每個變更附上一份 changeset 檔,寫明要發 patch、minor 還是 major。
| 項目 | aronrepo | semantic-release | release-please | changesets |
|---|---|---|---|---|
| 版本依據 | 固定的 commit 類型 | commit 訊息(預設 Angular 慣例,可換 preset) | Conventional Commits 訊息 | 另外撰寫的 changeset 檔 |
| minor、major 由誰決定 | explicit:擁有者寫 Bump;auto:commit 類型 | commit 類型與 BREAKING CHANGE | commit 類型與 !,可用 Release-As 指定版本 | 每份 changeset 宣告的等級 |
| 何時發版 | 預設推送到發布分支就發;也可手動觸發,發維護者批准的 commit | 推送到發布分支就發 | 合併 Release PR 時 | 執行 changeset version 與 publish,通常透過 Version Packages PR |
| 版本號存放 | 只在 git tag,不寫回 package.json | git tag;寫回要另裝 @semantic-release/git,官方不建議 | Release PR 寫入 package.json 與 manifest | changeset version 寫入 package.json |
| Release notes | GitHub Release 內文 | GitHub Release 內文;CHANGELOG.md 要另裝外掛 | CHANGELOG.md 與 GitHub Release | 各套件的 CHANGELOG.md |
| commit 檢查 | 內建 check:hook、PR 的每個 commit 與 PR 標題 | 無,另裝 commitlint | 無 | 不看 commit;changeset status 可檢查是否缺少 changeset |
| 沒改到發佈檔案的發版類型 commit | 合併前拒絕,不發版 | 依訊息照發 | 單一套件照發;monorepo 依變更路徑歸屬套件 | 不適用,發不發由 changeset 決定 |
| monorepo | 支援,所有套件共用一個版本 | 核心一次發一個套件,monorepo 要靠社群外掛 | manifest 設定,各套件獨立版本,可連動 | 主要設計對象,各套件獨立版本,可用 fixed、linked 綁定 |
| 發佈到 npm | 內建,先發到暫存 dist-tag,全部到位才切換 | 內建(@semantic-release/npm) | 不負責,工作流程要另寫發佈步驟 | 內建 changeset publish,只發 npm 上還沒有的版本 |
| 預發布 | alpha、beta、rc、canary 分支 | 預發布分支與 channel | prerelease 設定 | pre enter、pre exit 模式與 snapshot |
| 中斷後重跑 | 補上缺少的發佈、tag 與 Release | tag 在發佈前推送,發佈失敗要手動補救 | 不負責發佈 | 重跑 publish 會跳過已發佈的版本 |
| 發版前預覽 | explain(--json 含 commit 與 release notes)、release --dry-run | --dry-run | Release PR 本身 | changeset status |
| 給代理的規則 | policy --json、產生 AGENTS.md 區塊 | 無 | 無 | 無 |
| 適用範圍 | JavaScript,只發 npm | 多語言,靠外掛 | 多語言,各語言有對應 strategy | JavaScript 套件管理器的 workspace |
放到代理寫 commit 的情境,四者差在「誰在什麼時候定下版本等級」。semantic-release 由 commit 訊息當下決定,合併就發;release-please 同樣由訊息決定,但 Release PR 讓人在發版前再看一次版本號與 changelog;changesets 把等級寫在 changeset 檔裡,代理若負責寫 changeset,也就由代理選等級,靠 PR 評審把關;aronrepo 則在 explicit 模式下把 minor 與 major 從代理手上拿走,並在合併前拒絕不該發版的 commit。
如果需要各套件獨立版本,changesets 是較合適的選擇;需要多語言,或想在 GitHub 介面裡用合併 PR 完成發版確認,release-please 較合適;需要 npm 以外的發佈目標或特定外掛,semantic-release 的生態系最完整。
安裝規模
把功能收進一個套件,依賴也跟著變少。下面的數字是在全新目錄分別執行 npm install --ignore-scripts 的結果:套件數取 npm 回報的 added 數量,大小取 node_modules 的 du。semantic-release 單獨安裝不包含 commit 檢查,涵蓋範圍與 aronrepo 相當的是「semantic-release 加 commitlint」這一組;release-please 與 changesets 不檢查 commit,量的是本身的 CLI。
| 項目 | aronrepo | semantic-release | release-please | changesets |
|---|---|---|---|---|
| 量測套件 | aronrepo(當日最新版) | semantic-release 25.0.9 | release-please 17.11.2 | @changesets/cli 3.0.3 |
| Node.js 需求 | 22.18 以上 | ^22.14 或 24.10 以上 | 22 以上 | ^22.11、^24 或 26 以上 |
| 直接依賴 | 4 | 28 | 31 | 21 |
| 安裝後的套件總數 | 7 | 301(加 commitlint 為 345) | 162 | 40 |
node_modules 大小 | 2.7 MB | 79 MB(加 commitlint 為 105 MB) | 93 MB | 3.7 MB |
| 主套件解壓大小 | 366 kB | 128 kB | 929 kB | 89 kB |
安裝後的套件總數
aronrepo 安裝 7 個套件、changesets 40 個、release-please 162 個;涵蓋範圍與 aronrepo 相近的 semantic-release 加 commitlint 安裝 345 個。
- aronrepo7
- changesets 3(@changesets/cli)40
- release-please 17162
- semantic-release 25(不含 commit 檢查)301
- semantic-release 25 + commitlint345
查看套件數數據表
| 安裝組合 | 安裝的套件數 |
|---|---|
| aronrepo | 7 |
| changesets 3(@changesets/cli) | 40 |
| release-please 17 | 162 |
| semantic-release 25(不含 commit 檢查) | 301 |
| semantic-release 25 + commitlint | 345 |
2026 年 11 月 7 日於全新目錄執行 npm install --ignore-scripts,取 npm 回報的 added 數量。commitlint 組合包含 @commitlint/cli 與 @commitlint/config-conventional。
量測方式node_modules 大小
aronrepo 的 node_modules 約 2.7 MB、changesets 約 3.7 MB;release-please 約 93 MB,semantic-release 加 commitlint 約 105 MB。
- aronrepo2.7
- changesets 3(@changesets/cli)3.7
- release-please 1793
- semantic-release 25(不含 commit 檢查)79
- semantic-release 25 + commitlint105
查看安裝大小數據表
| 安裝組合 | MB(du 量測) |
|---|---|
| aronrepo | 2.7 |
| changesets 3(@changesets/cli) | 3.7 |
| release-please 17 | 93 |
| semantic-release 25(不含 commit 檢查) | 79 |
| semantic-release 25 + commitlint | 105 |
與上圖同一次安裝,以 du 量測 node_modules;不同檔案系統的區塊大小會讓數值略有差異。
量測方式和涵蓋範圍相當的 semantic-release 加 commitlint 相比,套件數從 345 降到 7,大小從約 105 MB 降到約 2.7 MB。aronrepo 主套件本身其實比 semantic-release 大(解壓後約 366 kB 對 128 kB),因為 commit 檢查與 CLI 都包在裡面;差距幾乎全部來自依賴樹。aronrepo 的直接依賴只有 semver、js-yaml、picomatch 與 tinyglobby 四個。
changesets 同樣輕量,因為它不解析 commit、也不建立 GitHub Release,這部分交給另外的 GitHub Action。release-please 的 CLI 安裝規模接近 semantic-release,但多數專案透過官方 GitHub Action 執行,不會進到專案的依賴裡。
適用條件與代價
aronrepo 的範圍是刻意收窄的。它只支援 ESM,需要 Node.js 22.18 以上;同一個 repo 裡所有發佈的套件共用一個版本號;打包使用專案的套件管理器,發佈一律透過 npm。想自訂 commit 類型、讓各套件各自跳版號,或使用 npm 以外的 registry 流程,都不在它的設計內。
已經有自己一套發版安全流程的專案,也不必整個換掉。CLI 背後的函式由 aronrepo/node 匯出,commit 規則、版本與 release notes 的工具函式則由 aronrepo 匯出;可以只讓 aronrepo 決定版本、tag 與 notes,打包、驗證與上傳仍交給原本的腳本。
我把 aronrepo 的重點放在一件事:把版本決策從「寫 commit 的人判斷得對不對」,移到「規則能不能在合併前擋下來」。代理照樣會挑錯類型,差別在於挑錯時,check 會拒絕它並給出替代寫法,而 minor 與 major 始終需要擁有者明確寫下。
