# Semantic Versioning ## Caution ![](https://i.imgur.com/eihl6iP.jpeg) ## Refereneces + 🔗 [**語意化版本**](https://semver.org/lang/zh-TW/) + 🔗 [**軟體版本週期**](https://zh.wikipedia.org/zh-tw/%E8%BB%9F%E4%BB%B6%E7%89%88%E6%9C%AC%E9%80%B1%E6%9C%9F) + 🔗 [**node-semver**](https://github.com/npm/node-semver?tab=readme-ov-file#versions) + ⚒️ [**semver-check**](https://jubianchi.github.io/semver-check) ## Version Syntax <code style="font-weight: bold;"> <span style="color: red">major</span>.<span style="color: seagreen">minor</span>.<span style="color: dodgerblue">patch</span>-<span style="color: mediumpurple">pre-release</span> </code> 1. **<span style="color: red;">主版號 major</span>**：當你做了<mark>不相容的 API 修改</mark> 2. **<span style="color: seagreen;">次版號 minor</span>**：當你做了<mark>向下相容的功能性新增</mark> 3. **<span style="color: dodgerblue;">修訂號 patch</span>**：當你做了<mark>向下相容的問題修正</mark> 4. **<span style="color: mediumpurple;">先行版 pre-release</span>**：<mark>非穩定版本</mark>，且可能無法達到相容的需求 ## Range Syntax ### Hyphen Ranges `-` + `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4` ### X-Ranges `x` | `X` | `*` + `*` := `>=0.0.0` + `1.x` := `>=1.0.0 <2.0.0-0` + `1.2.*` := `>=1.2.0 <1.3.0-0` ### Tilde Ranges `~` 若有指定 **<span style="color: seagreen;">minor</span>**，則只允許最高到 **<span style="color: dodgerblue;">patch</span>** 的變化 (<mark>不允許功能性新增</mark>)。 若無指定 **<span style="color: seagreen;">minor</span>**，則只允許最高到 **<span style="color: seagreen;">minor</span>** 的變化 (<mark>不允許不相容的 API 修改</mark>)。 + `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0` + `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0` (same as `1.2.x`) + `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0` (same as `1.x`) ### Caret Ranges `^` 只允許「指定版本」到 (不含)「最左側非 0 數字 +1 的版本」之間的版本 (<mark>不允許突破性更新 breaking change</mark>)。 + `^1.2.3` := `>=1.2.3 <2.0.0` + `^0.2.3` := `>=0.2.3 <0.3.0` + `^0.0.3` := `>=0.0.3 <0.0.4` ## PyPA Python 的版號又有一些更詳細的規定，詳見 [version-specifiers](https://packaging.python.org/en/latest/specifications/version-specifiers/)。 ``` <public version identifier>[+<local version label>] ``` ## public version identifier ### pre-release 正式版本前的非穩定版本。 ```py X.YaN # Alpha release X.YbN # Beta release X.YrcN # Release Candidate X.Y # Final release ``` ### pre-release 版本後的小修正，其和軟體運作本身無關，比如 Release Notes 的修正。 ```py X.Y.postN # Post-release X.YaN.postM # Post-release of an alpha release X.YbN.postM # Post-release of a beta release X.YrcN.postM # Post-release of a release candidate ``` ### developmental releases 開發階段的版號 ```py X.Y.devN # Developmental release X.YaN.devM # Developmental release of an alpha release X.YbN.devM # Developmental release of a beta release X.YrcN.devM # Developmental release of a release candidate X.Y.postN.devM # Developmental release of a post-release ``` ## local version identifier 通常是針對特定平台的變種版本，即便如此，它們也必須與原版本 API 兼容。\ 比如 `torch==2.6.0` (使用 CPU 的版本) 和 `torch==2.6.0+cu124` (針對使用 CUDA 的版本)。