Skip to content

Commit 49c9246

Browse files
Google-ML-AutomationGoogle-ML-Automation
committed
Merge pull request #25516 from jakevdp:jep-effver
PiperOrigin-RevId: 707923040
2 parents 8402a98 + 88c8941 commit 49c9246

File tree

2 files changed

+114
-0
lines changed

2 files changed

+114
-0
lines changed

‎docs/jep/25516-effver.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# JEP 25516: Effort-based versioning for JAX
2+
3+
This document proposes that the JAX core library should explicitly adopt
4+
**Effort-based versioning (EffVer)** for past and future releases.
5+
This versioning scheme is more fully described in
6+
[EffVer: Version your code by the effort required to upgrade](https://jacobtomlinson.dev/effver/).
7+
8+
The sections below discuss some of the considerations that favor this approach.
9+
10+
## Key features of EffVer
11+
Effort-based versioning is a three-number versioning system, similar to the better
12+
known semantic versioning ([SemVer](https://semver.org/)).
13+
It uses a three-number version of the form **MACRO** . **MESO** . **MICRO**,
14+
where version numbers are incremented based on the *expected effort*
15+
required to adapt to the change.
16+
17+
As an example, consider software with current version `2.3.4`:
18+
19+
- Increasing the **micro** version (i.e. releasing `2.3.5`) signals to users that
20+
little to no effort is necessary on their part to adapt to the changes.
21+
- Increasing the **meso** version (i.e. releasing `2.4.0`) signals to users that
22+
some small effort will be required for existing code to work with the changes.
23+
- Increasing the **macro** version (i.e. releasing `3.0.0`) signals to users that
24+
significant effort may be required to update to the changes.
25+
26+
In some ways, this captures the essence of more commonly-used semantic versioning,
27+
but avoids phrasing in terms of compatibility guarantees that are hard to meet
28+
in practice.
29+
30+
## Zero version
31+
In addition, EffVer gives special meaning to the Zero version. Early releases of
32+
software often are versioned `0.X.Y`, and in this case `X` has the characteristics
33+
of the macro version, and `Y` has the characteristics of the meso version.
34+
JAX has been in a zero-version state since its initial release (the version as of
35+
this writing is `0.4.37`), and EffVer’s zero-version case is a good *post-facto*
36+
description of the implicit intent behind JAX’s releases to date.
37+
38+
In EffVer, bumping from `0.X.Y` to version `1.0.0` is recommended when a certain
39+
level of stability has been reached in practice:
40+
41+
> If you end up on a version like `0.9.x` for many months it is a good signal that
42+
> things are pretty stable and that it’s time to switch to a `1.0.0` release.
43+
44+
- **Pros:**
45+
- EffVer concisely communicates the intent of a change, without making
46+
compatibility guarantees that are difficult to adhere to in practice.
47+
- EffVer, via its special casing of zero versions, correctly describes JAX’s
48+
release strategy prior to this proposal.
49+
- EffVer provides a concrete recommendation for how to think about JAX 1.0.
50+
- **Cons:**
51+
- EffVer is not as well-known as SemVer, and is not as immediately recognizable
52+
as CalVer, so may lead to some confusion among users.
53+
54+
## Alternatives considered
55+
56+
We considered a few alternatives to EffVer, outlined below. In each case, the
57+
Cons were judged to outweigh the Pros when evaluated against EffVer.
58+
59+
## Non-semantic versioning (status quo)
60+
JAX's current versioning uses three numbers with no formal semantic meaning
61+
beyond simple orderabilty (i.e. versions increase over time).
62+
In practice, JAX's version numbers up until now have been semantically quite
63+
similar to the EffVer zero-version case.
64+
65+
One option would be to explicitly formalize this non-semantic versioning.
66+
67+
- **Pros:**
68+
- The status quo requires no action from the development team.
69+
- **Cons:**
70+
- The status quo has led to confusion among users who expect the
71+
guarantees of SemVer to apply.
72+
- The status quo is unfriendly to users who would like some clear
73+
signal of the meaning of JAX releases.
74+
75+
### Semantic versioning
76+
One common alternative is Semantic versioning ([SemVer](https://semver.org/)).
77+
SemVer also encodes versions with three numbers, i.e.: **MAJOR** . **MINOR** . **MICRO**.
78+
Consider software with current version `2.3.4`:
79+
80+
- Increasing the **micro** version (i.e. releasing `2.3.5`) indicates the release
81+
includes only bug fixes.
82+
- Increasing the **minor** version (i.e. releasing `2.4.0`) indicates the release
83+
includes bug fixes as well as new features.
84+
- Increasing the **major** version (i.e. releasing `3.0.0`) indicates the release
85+
includes bug fixes, new features, as well as breaking changes.
86+
87+
SemVer makes no special accommodation for zero version, meaning that JAX’s existing
88+
releases violate the guarantees of the versioning scheme (up until this point, JAX
89+
has generally used the micro version for feature releases, and the minor version
90+
for significant backward-incompatible changes).
91+
92+
- **Pros:**
93+
- SemVer is well-known, and generally is the assumed model in the case of
94+
three-number versioning.
95+
- SemVer concisely describes the intent of each release.
96+
- **Cons**:
97+
- The compatibility guarantees of SemVer are difficult to achieve in practice.
98+
- SemVer has no special-casing for the zero version, and as such is not a good
99+
description of JAX’s release processes up until this point.
100+
101+
### Calendar versioning
102+
Another common versioning scheme is calendar-based versioning (CalVer), also typically
103+
represented by three numbers **YEAR** . **MONTH** . **DAY**. By design, these numbers
104+
contain no semantic meaning regarding the included changes, but rather encode the
105+
calendar data on which the software was released. For example, the `2024.12.16` release
106+
indicates that it reflects the state of the main branch on December 16, 2024.
107+
108+
- **Pros:**
109+
- CalVer immediately communicates the timestamp of the particular release, which
110+
may be difficult to determine in other versioning schemes.
111+
- **Cons:**
112+
- CalVer version numbers do not provide any signal to users regarding the degree
113+
of severity of the changes it includes.

‎docs/jep/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ Then create a pull request that adds a file named
5151
15856: `jax.extend`, an extensions module <15856-jex>
5252
17111: Efficient transposition of `shard_map` (and other maps) <17111-shmap-transpose>
5353
18137: Scope of JAX NumPy & SciPy Wrappers <18137-numpy-scipy-scope>
54+
25516: Effort-based versioning <25516-effver>
5455

5556

5657
Several early JEPs were converted in hindsight from other documentation,

0 commit comments

Comments
 (0)