Semver on Tarragonhttps://tarrragon.github.io/blog/tags/semver/Recent content in Semver on TarragonHugo -- gohugo.iozh-TWTarragon (CC BY 4.0)Thu, 25 Jun 2026 00:00:00 +0000改善類工作放進新功能版本 — 版本歸屬判斷的工具化https://tarrragon.github.io/blog/work-log/%E6%94%B9%E5%96%84%E9%A1%9E%E5%B7%A5%E4%BD%9C%E6%94%BE%E9%80%B2%E6%96%B0%E5%8A%9F%E8%83%BD%E7%89%88%E6%9C%AC-%E7%89%88%E6%9C%AC%E6%AD%B8%E5%B1%AC%E5%88%A4%E6%96%B7%E7%9A%84%E5%B7%A5%E5%85%B7%E5%8C%96/Thu, 25 Jun 2026 00:00:00 +0000https://tarrragon.github.io/blog/work-log/%E6%94%B9%E5%96%84%E9%A1%9E%E5%B7%A5%E4%BD%9C%E6%94%BE%E9%80%B2%E6%96%B0%E5%8A%9F%E8%83%BD%E7%89%88%E6%9C%AC-%E7%89%88%E6%9C%AC%E6%AD%B8%E5%B1%AC%E5%88%A4%E6%96%B7%E7%9A%84%E5%B7%A5%E5%85%B7%E5%8C%96/<h2 id="事件">事件</h2> <p>v0.3.0 發布後發現一個測試隔離問題，v0.3.1 做了 hotfix。接著要做根因分析和系統性防護（重構 + 品質規則更新）。</p> <p>建立工作項目時指定了 <code>--version 0.4.0</code>——v0.3.0 和 v0.3.1 都已發布，v0.4.0 是下一個功能版本。工具接受了，沒有提示。</p> <p>結果：三張改善類工作（根因分析、State Registry 重構、品質規則文件）和 PostgreSQL Storage Backend 混在同一個版本裡。改善和新功能綁定發布，語意混亂。事後建立 v0.3.2 遷移工作項目並重新發布。</p> <h2 id="根因工具只做格式驗證">根因：工具只做格式驗證</h2> <p><code>ticket create --version 0.4.0</code> 被接受的條件是「v0.4.0 存在於版本清單且為 active」。工具不分析工作類型（分析 / 修復 / 重構 / 新功能）和版本層級（MINOR / PATCH）的匹配度。</p> <p>semver 有明確的語意分工——MINOR 用於新功能，PATCH 用於修復和改善。這個語意可以被工具表達：</p> <table> <thead> <tr> <th>工作類型</th> <th>semver 語意</th> <th>建議版本</th> </tr> </thead> <tbody> <tr> <td>新功能</td> <td>MINOR bump</td> <td>下一個功能版本</td> </tr> <tr> <td>修復</td> <td>PATCH bump</td> <td>當前系列的下一個 patch</td> </tr> <tr> <td>改善 / 重構</td> <td>PATCH bump</td> <td>同上</td> </tr> <tr> <td>文件</td> <td>PATCH bump</td> <td>同上</td> </tr> </tbody> </table> <p>工具可以根據工作類型自動建議版本，使用者可以覆蓋。建議錯了，使用者多打一個參數；沉默錯了，事後遷移。</p> <h2 id="教訓">教訓</h2> <p><strong>語意已經存在，工具有責任表達它。</strong> semver 的 MINOR/PATCH 分工是廣泛認知的慣例。但「知道」和「每次建立工作項目時都記得套用」是兩件事。工具可以把這個「記得套用」的成本降到零：讀取工作類型，對照 semver 語意，輸出建議。</p> <p>這個 pattern 適用於任何「輸入涉及分類判斷」的工具介面。工具不需要代替使用者做決策，但可以把分類規則從「腦中的知識」轉化為「介面上的提示」。同一次版本檢視中發現的另一個工具盲區（狀態殘留）見 <a href="https://tarrragon.github.io/blog/work-log/%E7%89%88%E6%9C%AC%E7%8B%80%E6%85%8B%E6%AE%98%E7%95%99%E7%82%BA%E4%BB%80%E9%BA%BC%E5%B7%B2%E5%AE%8C%E6%88%90%E7%9A%84%E7%89%88%E6%9C%AC%E5%9C%A8%E7%9C%8B%E6%9D%BF%E4%B8%8A%E9%A1%AF%E7%A4%BA%E6%9C%AA%E5%AE%8C%E6%88%90/" data-link-title="版本狀態殘留：為什麼已完成的版本在看板上顯示未完成" data-link-desc="看板顯示早已完成的版本仍為 active、誤導查看者。根因是發布工具只檢查當前版本完成度、不掃前版本的狀態殘留；工具的檢查範圍決定了系統的一致性邊界。">version_status_residual_ghost</a>。</p>事件

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。

]]>