事件

v0.3.0 發布後發現一個測試隔離問題,v0.3.1 做了 hotfix。接著要做根因分析和系統性防護(重構 + 品質規則更新)。

建立工作項目時指定了 --version 0.4.0——v0.3.0 和 v0.3.1 都已發布,v0.4.0 是下一個功能版本。工具接受了,沒有提示。

結果:三張改善類工作(根因分析、State Registry 重構、品質規則文件)和 PostgreSQL Storage Backend 混在同一個版本裡。改善和新功能綁定發布,語意混亂。事後建立 v0.3.2 遷移工作項目並重新發布。

根因:工具只做格式驗證

ticket create --version 0.4.0 被接受的條件是「v0.4.0 存在於版本清單且為 active」。工具不分析工作類型(分析 / 修復 / 重構 / 新功能)和版本層級(MINOR / PATCH)的匹配度。

semver 有明確的語意分工——MINOR 用於新功能,PATCH 用於修復和改善。這個語意可以被工具表達:

工作類型semver 語意建議版本
新功能MINOR bump下一個功能版本
修復PATCH bump當前系列的下一個 patch
改善 / 重構PATCH bump同上
文件PATCH bump同上

工具可以根據工作類型自動建議版本,使用者可以覆蓋。建議錯了,使用者多打一個參數;沉默錯了,事後遷移。

教訓

語意已經存在,工具有責任表達它。 semver 的 MINOR/PATCH 分工是廣泛認知的慣例。但「知道」和「每次建立工作項目時都記得套用」是兩件事。工具可以把這個「記得套用」的成本降到零:讀取工作類型,對照 semver 語意,輸出建議。

這個 pattern 適用於任何「輸入涉及分類判斷」的工具介面。工具不需要代替使用者做決策,但可以把分類規則從「腦中的知識」轉化為「介面上的提示」。同一次版本檢視中發現的另一個工具盲區(狀態殘留)見 version_status_residual_ghost