語意版本的自動化,本質上是把「下一版該發多少」交給 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:紙卡只推動 patch,minor 與 major 要等擁有者開鎖。右邊是 auto:commit 類型經由齒輪直接決定哪一位數前進。

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),就會被要求改成不發版的類型。

一排白色紙卡分別畫著包裹、網頁視窗與試管圖示,經過木框金屬篩網:包裹卡片進入木箱,網頁與試管卡片沿著金屬軌道排進一旁的白色紙盒。
只有改到發佈套件內容的 commit 會進入發版;網站與測試的改動照樣合併,但不會觸發版本。

每個決定都說得出理由

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.4

release 會先確認簽出的 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。

項目aronreposemantic-releaserelease-pleasechangesets
版本依據固定的 commit 類型commit 訊息(預設 Angular 慣例,可換 preset)Conventional Commits 訊息另外撰寫的 changeset 檔
minor、major 由誰決定explicit:擁有者寫 Bump;auto:commit 類型commit 類型與 BREAKING CHANGEcommit 類型與 !,可用 Release-As 指定版本每份 changeset 宣告的等級
何時發版預設推送到發布分支就發;也可手動觸發,發維護者批准的 commit推送到發布分支就發合併 Release PR 時執行 changeset version 與 publish,通常透過 Version Packages PR
版本號存放只在 git tag,不寫回 package.jsongit tag;寫回要另裝 @semantic-release/git,官方不建議Release PR 寫入 package.json 與 manifestchangeset version 寫入 package.json
Release notesGitHub 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 分支預發布分支與 channelprerelease 設定pre enter、pre exit 模式與 snapshot
中斷後重跑補上缺少的發佈、tag 與 Releasetag 在發佈前推送,發佈失敗要手動補救不負責發佈重跑 publish 會跳過已發佈的版本
發版前預覽explain(--json 含 commit 與 release notes)、release --dry-run--dry-runRelease PR 本身changeset status
給代理的規則policy --json、產生 AGENTS.md 區塊無無無
適用範圍JavaScript,只發 npm多語言,靠外掛多語言,各語言有對應 strategyJavaScript 套件管理器的 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。

項目aronreposemantic-releaserelease-pleasechangesets
量測套件aronrepo(當日最新版)semantic-release 25.0.9release-please 17.11.2@changesets/cli 3.0.3
Node.js 需求22.18 以上^22.14 或 24.10 以上22 以上^22.11、^24 或 26 以上
直接依賴4283121
安裝後的套件總數7301(加 commitlint 為 345)16240
node_modules 大小2.7 MB79 MB(加 commitlint 為 105 MB)93 MB3.7 MB
主套件解壓大小366 kB128 kB929 kB89 kB

安裝後的套件總數

npm install --ignore-scripts · added · 2026-11-07

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
查看套件數數據表
安裝後的套件總數 · 安裝的套件數
安裝組合安裝的套件數
aronrepo7
changesets 3(@changesets/cli)40
release-please 17162
semantic-release 25(不含 commit 檢查)301
semantic-release 25 + commitlint345

2026 年 11 月 7 日於全新目錄執行 npm install --ignore-scripts,取 npm 回報的 added 數量。commitlint 組合包含 @commitlint/cli 與 @commitlint/config-conventional。

量測方式

node_modules 大小

npm install --ignore-scripts · du node_modules · 2026-11-07

aronrepo 的 node_modules 約 2.7 MB、changesets 約 3.7 MB;release-please 約 93 MB,semantic-release 加 commitlint 約 105 MB。

MB(du 量測)
  • aronrepo2.7
  • changesets 3(@changesets/cli)3.7
  • release-please 1793
  • semantic-release 25(不含 commit 檢查)79
  • semantic-release 25 + commitlint105
查看安裝大小數據表
node_modules 大小 · MB(du 量測)
安裝組合MB(du 量測)
aronrepo2.7
changesets 3(@changesets/cli)3.7
release-please 1793
semantic-release 25(不含 commit 檢查)79
semantic-release 25 + commitlint105

與上圖同一次安裝,以 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 始終需要擁有者明確寫下。