JEP 25516：JAX 的基於努力程度的版本控制

JEP 25516：JAX 的基於努力程度的版本控制#

本文件提議 JAX 核心函式庫應明確採用基於努力程度的版本控制 (Effort-based versioning, EffVer) 用於過去和未來的版本。此版本控制方案在EffVer：依升級所需的努力程度為你的程式碼進行版本控制中有更完整的描述。

以下章節討論一些支持此方法的考量。

EffVer 的主要特性#

基於努力程度的版本控制是一種三位數版本控制系統，類似於更廣為人知的語意化版本控制 (SemVer)。它使用 MACRO . MESO . MICRO 形式的三位數版本，其中版本號碼根據適應變更所需的預期努力程度來遞增。

例如，考慮目前版本為 2.3.4 的軟體

增加 micro 版本（即發布 2.3.5）向使用者表示他們幾乎不需要付出任何努力來適應這些變更。
增加 meso 版本（即發布 2.4.0）向使用者表示現有程式碼需要付出一些小的努力才能與變更協同工作。
增加 macro 版本（即發布 3.0.0）向使用者表示更新到這些變更可能需要付出相當大的努力。

在某些方面，這捕捉了更常被使用的語意化版本控制的本質，但避免以實務上難以實現的相容性保證來措辭。

零版本#

此外，EffVer 為零版本賦予特殊意義。軟體的早期版本通常會進行版本控制 0.X.Y，在這種情況下，X 具有 macro 版本的特性，而 Y 具有 meso 版本的特性。JAX 自最初發布以來一直處於零版本狀態（截至撰寫本文時的版本為 0.4.37），而 EffVer 的零版本案例是對 JAX 迄今為止發布版本背後的隱含意圖的良好事後描述。

在 EffVer 中，當實際上達到一定程度的穩定性時，建議從 0.X.Y 升級到 1.0.0 版本

如果您最終停留在像 0.9.x 這樣的版本好幾個月，這是一個很好的信號，表明情況相當穩定，而且是時候切換到 1.0.0 版本了。

優點
- EffVer 簡潔地傳達變更的意圖，而不做出實務上難以遵守的相容性保證。
- EffVer 透過其零版本的特殊情況，正確地描述了此提案之前 JAX 的發布策略。
- EffVer 為如何思考 JAX 1.0 提供了具體建議。
缺點
- EffVer 不如 SemVer 廣為人知，也不如 CalVer 那麼容易辨識，因此可能會導致使用者之間的一些混淆。

考量的替代方案#

我們考量了 EffVer 的一些替代方案，概述如下。在每種情況下，與 EffVer 比較評估時，缺點都被認為超過優點。

非語意化版本控制 (現狀)#

JAX 目前的版本控制使用三個數字，除了簡單的可排序性之外，沒有正式的語意含義（即版本隨時間增加）。實際上，到目前為止，JAX 的版本號碼在語意上與 EffVer 的零版本案例非常相似。

一個選項是明確地將這種非語意化版本控制形式化。

優點
- 現狀讓開發團隊無需採取任何行動。
缺點
- 現狀已導致使用者之間的混淆，他們期望 SemVer 的保證適用。
- 現狀對於想要 JAX 版本發布意義的一些明確信號的使用者不友善。

語意化版本控制#

一個常見的替代方案是語意化版本控制 (SemVer)。SemVer 也用三個數字編碼版本，即：MAJOR . MINOR . MICRO。考慮目前版本為 2.3.4 的軟體

增加 micro 版本（即發布 2.3.5）表示該版本僅包含錯誤修復。
增加 minor 版本（即發布 2.4.0）表示該版本包含錯誤修復以及新功能。
增加 major 版本（即發布 3.0.0）表示該版本包含錯誤修復、新功能以及破壞性變更。

SemVer 沒有為零版本做出特殊安排，意味著 JAX 現有的版本發布違反了版本控制方案的保證（直到目前為止，JAX 通常使用微版本進行功能發布，而次要版本用於重大的向後不相容變更）。

優點
- SemVer 廣為人知，並且通常是三位數版本控制的假設模型。
- SemVer 簡潔地描述每個版本的意圖。
缺點:
- SemVer 的相容性保證在實務上難以實現。
- SemVer 沒有為零版本進行特殊處理，因此不是對 JAX 發布過程的良好描述。

日曆版本控制#

另一個常見的版本控制方案是基於日曆的版本控制 (CalVer)，通常也用三個數字 YEAR . MONTH . DAY 表示。依設計，這些數字不包含關於所含變更的任何語意含義，而是編碼軟體發布的日曆日期。例如，2024.12.16 版本發布表示它反映了 2024 年 12 月 16 日主分支的狀態。

優點
- CalVer 立即傳達特定版本的時間戳記，這在其他版本控制方案中可能難以確定。
缺點
- CalVer 版本號碼不向使用者提供關於它包含的變更的嚴重程度的任何信號。