JEP 25516: JAX 基于工作量的版本控制

JEP 25516: JAX 基于工作量的版本控制#

本提案已于 0.5.0 版本采纳

本文件提议 JAX 核心库应明确采用基于工作量的版本控制 (Effort-based versioning, EffVer) 用于过去和未来的版本发布。该版本控制方案在 EffVer：根据升级所需工作量对代码进行版本管理中有更详细的描述。

以下各节讨论了支持采用此方案的一些考量因素。

EffVer 的主要特征#

基于工作量的版本控制是一个三位数字的版本系统，类似于众所周知的语义版本控制 (SemVer)。它使用 MACRO（宏版本）. MESO（中版本）. MICRO（微版本）形式的三位数字版本，其中版本号的递增取决于适应变更所需的预期工作量。

例如，假设当前软件版本为 2.3.4

增加微版本（例如发布 2.3.5）向用户表明，他们几乎无需付出任何努力即可适应这些变更。
增加中版本（例如发布 2.4.0）向用户表明，现有的代码需要付出少量努力才能配合这些变更工作。
增加宏版本（例如发布 3.0.0）向用户表明，更新到该版本可能需要付出重大的努力。

在某些方面，这抓住了更常用的语义版本控制的精髓，但避免了在实践中难以实现的兼容性保证措辞。

零版本#

此外，EffVer 对零版本赋予了特殊的含义。软件的早期版本通常被标记为 0.X.Y，在这种情况下，X 具有宏版本的特征，而 Y 具有中版本的特征。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 的软件：

增加修订版本（例如发布 2.3.5）表明该版本仅包含错误修复。
增加次版本（例如发布 2.4.0）表明该版本既包含错误修复也包含新功能。
增加主版本（例如发布 3.0.0）表明该版本既包含错误修复和新功能，也包含破坏性变更。

SemVer 没有针对零版本进行特殊处理，这意味着 JAX 现有的发布版本违反了该版本控制方案的保证（在此之前，JAX 通常使用修订版本来发布功能，使用次版本来进行重大的向后不兼容变更）。

优点
- SemVer 众所周知，通常是三位数字版本控制情况下的默认模型。
- SemVer 简洁地描述了每个发布的意图。
缺点:
- SemVer 的兼容性保证在实践中很难实现。
- SemVer 没有针对零版本的特殊处理，因此不能很好地描述 JAX 到目前为止的发布流程。

日期版本控制#

另一种常见的版本控制方案是基于日期的版本控制 (CalVer)，通常也由三个数字表示：YEAR（年）. MONTH（月）. DAY（日）。根据设计，这些数字不包含关于所含变更的任何语义含义，而是编码了软件发布的日期。例如，2024.12.16 版本表明它反映了 2024 年 12 月 16 日主分支的状态。

优点
- CalVer 可以直接传达特定版本的时间戳，这在其他版本控制方案中可能很难确定。
缺点
- CalVer 版本号不向用户提供关于所含变更严重程度的任何信号。