語義化版本2.0.0

標籤：style   http   io   ar   os   使用   sp   檔案   on   

摘要

版本格式：主要版本號.次版本號碼.修訂編號，版本號碼遞增規則如下：

1. 主要版本號：當你做了不相容的API 修改，

2. 次版本號碼：當你做了向下相容的功能性新增，

3. 修訂編號：當你做了向下相容的問題修正。

先行版本號碼及版本編譯資訊可以加到“主要版本號.次版本號碼.修訂編號”的後面，作為延伸。

簡介

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

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

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

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

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

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

1. 使用語意化版本控制系統的軟體“必須MUST”定義公用API。該API可以在代碼中被定義或出現於嚴謹的檔案內。無論何種形式都應該力求精確且完整。

2. 標準的版本號碼“必須MUST”採用XYZ的格式， 其中X、Y和Z為非負的整數，且“禁止MUST NOT”在數字前方補零。X是主要版本號、Y是次版本號碼、而Z為修訂編號。每個元素“必須MUST”以數值來遞增。例如：1.9.1 -> 1.10.0 -> 1.11.0。

3. 標記版本號碼的軟體發行後，“禁止MUST NOT”改變該版本軟體的內容。任何修改都“必須MUST”以新版本發行。

4. 主要版本號為零（0.yz）的軟體處於開發初始階段，一切都可能隨時被改變。這樣的公用API 不應該被視為穩定版。

5. 1.0.0 的版本號碼用於界定公用API 的形成。這一版本之後所有的版本號碼更新都基於公用API 及其修改內容。

6. 修訂編號Z（xyZ | x > 0）“必須MUST”在只做了向下相容的修正時才遞增。這裡的修正指的是針對不正確結果而進行的內部修改。

7. 次版本號碼Y（xYz | x > 0）“必須MUST”在有向下相容的新功能出現時遞增。在任何公用API的功能被標記為棄用時也“必須MUST”遞增。也“可以MAY”在內部程式有大量新功能或改進被加入時遞增，其中“可以MAY”包括修訂層級的改變。每當次版本號碼遞增時，修訂編號“必須MUST”歸零。

8. 主要版本號X（Xyz | X > 0）“必須MUST”在有任何不相容的修改被加入公用API時遞增。其中“可以MAY”包括次版本號碼及修訂層級的改變。每當主要版本號遞增時，次版本號碼和修訂編號“必須MUST”歸零。

9. 先行版本號碼“可以MAY”被標註在修訂版之後，先加上一個串連號再加上一連串以句點分隔的標識符號來修飾。標識符號“必須MUST”由ASCII碼的英數字和串連號[0-9A-Za-z-]組成，且“禁止MUST NOT”留白。數字型的標識符號“禁止MUST NOT”在前方補零。先行版的優先順序低於相關聯的標準版本。被標上先行版本號碼則表示這個版本並非穩定而且可能無法達到相容的需求。範例：1.0.0-alpha、1.0.0-alpha.1、 1.0.0-0.3.7、1.0.0-x.7.z.92。

10. 版本編譯資訊“可以MAY”被標註在修訂版或先行版本號碼之後，先加上一個加號再加上一連串以句點分隔的標識符號來修飾。標識符號“必須MUST”由ASCII的英數字和串連號[0-9A-Za-z-]組成，且“禁止MUST NOT”留白。當判斷版本的優先層級時，版本編譯資訊“可SHOULD”被忽略。因此當兩個版本只有在版本編譯資訊有差別時，屬於相同的優先層級。範例：1.0.0-alpha+001、1.0.0+20130313144700、 1.0.0-beta+exp.sha.5114f85。

11. 版本的優先層級指的是不同版本在排序時如何比較。判斷優先層級時，“必須MUST”把版本依序拆分為主要版本號、次版本號碼、修訂編號及先行版本號碼後進行比較（版本編譯資訊不在這份比較的列表中）。由左到右依序比較每個標識符號，第一個差異值用來決定優先層級：主要版本號、次版本號碼及修訂編號以數值比較，例如1.0.0 < 2.0.0 < 2.1.0 < 2.1.1。當主要版本號、次版本號碼及修訂編號都相同時，改以優先層級比較低的先行版本號碼決定。例如：1.0.0-alpha < 1.0.0。有相同主要版本號、次版本號碼及修訂編號的兩個先行版本號碼，其優先層級“必須MUST”透過由左到右的每個被句點分隔的標識符號來比較，直到找到一個差異值後決定：只有數位標識符號以數值高低比較，有字母或串連號時則逐字以ASCII的排序來比較。數位標識符號比非數位標識符號優先層級低。若開頭的標識符號都相同時，欄 位比較多的先行版本號碼優先層級比較高。範例：1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0- rc.1 < 1.0.0。

為什麼要使用語義化的版本控制？

這並不是一個新的或者革命性的想法。實際上，你可能已經在做一些近似的事情了。問題在於只是“近似”還不夠。如果沒有某個正式的規範可循，版本號碼對於依賴的管理並無實質意義。將上述的想法命名並給予清楚的定義，讓你對軟體使用者傳達意向變得容易。一旦這些意向變得清楚，彈性（但又不會太彈性）的依賴規範就能達成。

舉個簡單的例子就可以展示語義化的版本控制如何讓依賴地獄成為過去。假設有個名為“救火車”的函式庫，它需要另一個名為“梯子”並已經有使用語意化版本控制系統的套件。當救火車建立時，梯子的版本號碼為3.1.0。因為救火車使用了一些版本3.1.0 所新增的功能， 你可以放心地指定相依於梯子的版本號碼大等於3.1.0 但小於4.0.0。這樣，當梯子版本3.1.1 和3.2.0 發布時，你可以將直接它們納入你的套件管理系統，因為它們能與原有相依的軟體相容。

作為一位負責任的開發人員，你理當確保每次套件升級的運作與版本號碼的表述一致。現實世界是複雜的，我們除了提高警覺外能做的不多。你所能做的就是讓語義化的版本控製為你提供一個健全的方式來發行以及升級套件，而無需推出新的相依套件，節省你的時間及煩惱。

如果你對此認同，希望立即開始使用語意化版本控制系統，你只需聲明你的函式庫正在使用它並遵循這些規則就可以了。請在你的README 檔案中保留此頁連結，讓別人也知道這些規則並從中受益。

FAQ 在0.y.z 初始開發階段，我該如何進資料列版本設定？

最簡單的做法是以0.1.0 作為你的初始化開發版本，並在後續的每次發行時遞增次版本號碼。

如何判斷髮布1.0.0 版本的時機？

當你的軟體被用於正式環境，它應該已經達到了1.0.0 版。如果你已經有個穩定的API 被使用者依賴，也會是1.0.0 版。如果你很擔心向下相容的問題，也應該算是1.0.0 版了。

這不會阻礙快速開發和迭代嗎？

主要版本號為零的時候就是為了做快速開發。如果你每天都在改變API，那麼你應該仍在主要版本號為零的階段（0.yz），或是正在下個主要版本的獨立開發分支中。

對於公用API，若即使是最小但不向下相容的改變都需要產生新的主要版本號，豈不是很快就達到42.0.0 版？

這是開發的責任感和前瞻性的問題。不相容的改變不應該輕易被加入到有許多依賴代碼的軟體中。升級所付出的代價可能是巨大的。要遞增主要版本號來發行不相容的改版，意味著你必須為這些改變所帶來的影響深思熟慮，並且評估所涉及的成本及效益比。

為整個公用API寫檔案太費事了！

為供他人使用的軟體編寫適當的檔案，是你作為一名專業開發人員應盡的職責。保持專案高效一個非常重要的部份是掌控軟體的複雜度，如果沒有人知道如何使用你的軟體或不知道哪些函數的調用是可靠的，要掌控複雜度會是困難的。長遠來看，使用語意化版本控制系統以及對於公用API 有良好規範的堅持，可以讓每個人及每件事都運行順暢。

萬一不小心把一個不相容的改版當成了次版本號碼發行了該怎麼辦？

一旦發現自己破壞了語意化版本控制系統的規範，就要修正這個問題，並發行一個新的次版本號碼來更正這個問題並且恢複向下相容。即使是這種情況，也不能去修改已發行的版本。可以的話，將有問題的版本號碼記錄到檔案中，告訴使用者問題所在，讓他們能夠意識到這是有問題的版本。

如果我更新了自己的依賴但沒有改變公用API 該怎麼辦？

由於沒有影響到公用API，這可以被認定是相容的。若某個軟體和你的套件有共同依賴， 則它會有自己的依賴規範，作者也會告知可能的衝突。要判斷改版是屬於修訂等級或是次版等級，是依據你更新的依賴關係是為了修複問題或是加入新功能。對於後者，我經常會預期伴隨著更多的代碼，這顯然會是一個次版本號碼層級的遞增。

如果我變更了公用API 但無意中未遵循版本號碼的改動怎麼辦呢？（意即在修訂等級的發布中，誤將重大且不相容的改變加到代碼之中）

自行做最佳的判斷。如果你有龐大的使用者群在依照公用API 的意圖而變更行為後會大受影響，那麼最好做一次主要版本的發布，即使嚴格來說這個修複僅是修訂等級的發布。記住， 語義化的版本控制就是透過版本號碼的改變來傳達意義。若這些改變對你的使用者是重要的，那就透過版本號碼來向他們說明。

我該如何處理即將棄用的功能？

棄用現存的功能是軟體開發中的家常便飯，也通常是向前發展所必須的。當你棄用部份公用API 時，你應該做兩件事：（1）更新你的檔案讓使用者知道這個改變，（2）在適當的時機將棄用的功能透過新的次版本號碼發布。在新的主要版本完全移除棄用功能前，至少要有一個次版本包含這個棄用資訊，這樣使用者才能平順地轉移到新版API。

語義化版本對於版本的字串長度是否有限制呢？

沒有，請自行做適當的判斷。舉例來說，長到255 個字元的版本已過度誇張。再者，特定的系統對於字串長度可能會有他們自己的限制。

關於

語意化版本控制系統的規範是由Gravatars創辦者兼GitHub共同創辦者Tom Preston-Werner所建立。

如果您有任何建議，請到GitHub上提出您的問題。

授權

創用CC 姓名標示3.0 Unported 授權條款http://creativecommons.org/licenses/by/3.0/

語義化版本2.0.0