語意化版本 | Notion

來源

摘要

版本格式：主版號。次版號。修訂號，版號遞增規則如下：

主版號：當你做了不相容的 API 修改，
次版號：當你做了向下相容的功能性新增，
修訂號：當你做了向下相容的問題修正。

先行版號及版本編譯資訊可以加到「主版號。次版號。修訂號」的後面，作為延伸。

簡介

在軟體管理的領域裡存在著被稱作「相依性地獄」的死亡之谷，系統規模越大，加入的套件越多，你就越有可能在未來的某一天發現自己已深陷絕望之中。

在相依性高的系統中發佈新版本套件可能很快會成為惡夢。如果相依性關係過高，可能面臨版本控制被鎖死的風險（必須對每一個相依套件改版才能完成某次升級）。而如果相依性關係過於鬆散，又將無法避免版本的混亂（假設相容於未來的多個版本已超出了合理數量）。當你專案的進展因為版本相依被鎖死或版本混亂變得不夠簡便和可靠，就意味著你正處於相依性地獄之中。

作為這個問題的解決方案之一，我提議用一組簡單的規則及條件來約束版號的配置和增長。這些規則是根據（但不局限於）已經被各種封閉、開放源碼軟體所廣泛使用的慣例所設計。為了讓這套理論運作，你必須先有定義好的公共 API。這可以透過文件定義或程式碼強制要求來實現。無論如何，這套 API 的清楚明瞭是十分重要的。一旦你定義了公共 API，你就可以透過修改相應的版號來向大家說明你的修改。考慮使用這樣的版號格式：X.Y.Z（主版號。次版號。修訂號）修復問題但不影響 API 時，遞增修訂號；API 保持向下相容的新增及修改時，遞增次版號；進行不向下相容的修改時，遞增主版號。

我稱這套系統為「語意化的版本控制」，在這套約定下，版號及其更新方式包含了相鄰版本間的底層程式碼和修改內容的訊息。

語意化版本控制規範（SemVer）

以下關鍵詞「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、「OPTIONAL」依照 RFC 2119 的敘述解讀。（譯著：為了保持語句順暢，以下文件遇到的關鍵詞將依照整句語意進行翻譯，在此先不進行個別翻譯。）

使用語意化版本控制的軟體必須（MUST）定義公共 API。該 API 可以在程式碼中被定義或出現於嚴謹的文件內。無論何種形式都應該（SHOULD）力求精確且完整。
標準的版號必須（MUST）採用 X.Y.Z 的格式，其中 X、Y 和 Z 為非負的整數，且禁止（MUST NOT）在數字前方補零。X 是主版號、Y 是次版號、而 Z 為修訂號。每個元素必須（MUST）以數值來遞增。例如：1.9.1 -> 1.10.0 -> 1.11.0。
標記版號的軟體發行後，禁止（MUST NOT）改變該版本軟體的內容。任何修改都必須（MUST）以新版本發行。
主版號為零（0.y.z）的軟體處於開發初始階段，一切都可以（MAY）隨時改變。這樣的公共 API 不應該（SHOULD NOT）被視為穩定版。