語意化版本
Semantic Versioning
什麼是語意化版本?
- 以主.次.修三段式編號標示版本
- 以數字掌握變更性質
- 相容性管理
語意化版本真正改變的,是「由誰來判斷要不要更新」。沒有規則時,所有人都得逐一閱讀發行說明再決定;有了規則,套件管理工具就會機械式地執行「次版本以內自動升級,主版本不要動」這道指令。package.json 裡的 ^1.4.0、Python 裡的 ~=1.4 這類寫法,就是這道指令本身。人工確認作業轉移到了工具的設定值上,這是重點;因此即使有 200 到 300 個相依套件的專案,也能以只由人工檢查主版本已變更的項目的方式順利運作。
細部條件中,有實務人員常忽略的例外。0.y.z 區間不受規則保護,官方規格也明文寫道「0.x 版本隨時可能破壞相容性」。一旦發布 1.0.0,公開 API 就等於被凍結。像 1.0.0-beta.2 這種連字號後接的預發布版本,會被視為比正式版 1.0.0 更低的版本;加號後的建置中繼資料(build metadata)則在比較時完全被忽略。與 Ubuntu 24.04 那種以日期當版本號的 CalVer 目的不同,若在同一組織內混用,只會徒增混亂。
現場最常見的誤解,是把版本號當成保證。版本號其實只是部署者自行標上的宣告而已,並非經過驗證的事實。實際上,有不少函式庫會以「修補版本」之名,悄悄更動預設設定值;公司內部團隊也常因為「升主版本會讓其他團隊不高興」,把會破壞相容性的變更藏進次版本裡。再加上若沒有把 lock 檔案提交到版本庫,同一條安裝指令在開發者電腦與正式伺服器上可能得出不同結果,而光是找出故障原因就可能耗掉好幾天。
由 Tom Preston-Werner(GitHub 共同創辦人)整理的規格(semver.org),已成為開源生態系的事實標準。
以下用一個假設案例來說明。A 公司經營員工約 140 人規模的物流 SaaS,光是去年第四季就在部署後連續發生三次故障。追查原因後發現,三件都源自外部函式庫的自動更新,其中兩件只是版本號最後一位改變的「錯誤修正」。
- 後端負責人金責任調查了一個月的部署紀錄,發現自動升級的套件有 47 個,而 lock 檔案甚至沒有提交到儲存庫。
- CTO 質問「只有末碼升上去,服務為什麼會掛掉?」金負責人便把認證函式庫從 0.9.3 升級到 0.9.4 的 commit 投到螢幕上:權杖到期的預設值從 24 小時改成了 1 小時。
- 團隊在儲存庫 README 最上方加上了三行規則:0.x 套件一律鎖定整個版本,^ 範圍只用於 1.0.0 以上,lock 檔案則一律 commit,毫無例外。
- 將同一標準套用到公司內部 12 個共用模組,並把「只要刪除任一 API 回應欄位,就升級主版本」這項寫入程式碼審查檢查表。第一個月,結算模組就從 2.7.0 升到了 3.0.0。
- 半年後,部署後立即發生的故障從每季 3 件降為 0 件,審查一則更新 PR 的時間也從平均 40 分鐘縮短為 10 分鐘。
Seung-tae Park
金鍾赫