Skip to content

Commit 70898d7

Browse files
committed
Add versioning section to "future API standard evolution"
1 parent 05026cd commit 70898d7

File tree

1 file changed

+27
-1
lines changed

1 file changed

+27
-1
lines changed

spec/future_API_evolution.md

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,30 @@
1010

1111
## Versioning
1212

13-
13+
This API standard uses the following versioning scheme:
14+
15+
- The version is date-based, in the form `yyyy.mm` (e.g., `2020.12`).
16+
- The version shall not include a standard way to do `alpha`/`beta`/`rc` or
17+
`.post`/`.dev` type versions.
18+
_Rationale: that's for Python packages, not for a standard._
19+
- The version must be made available at runtime via an attribute
20+
`__array_api_version__` by a compliant implementation, in `'yyyy.mm'` format
21+
as a string, in the namespace that implements the API standard.
22+
_Rationale: dunder version strings are the standard way of doing this._
23+
24+
No utilities for dealing with version comparisons need to be provided; given
25+
the format simple string comparisons with Python operators (`=-`, `<`, `>=`,
26+
etc.) will be enough.
27+
28+
.. note::
29+
30+
Rationale for the `yyyy.mm` versioning scheme choice:
31+
the API will be provided as part of a library, which already has a versioning
32+
scheme (typically PEP 440 compliant and in the form `major.minor.bugfix`),
33+
and a way to access it via `module.__version__`. The API standard version is
34+
completely independent from the package version. Given the standardization
35+
process, it resembles a C/C++ versioning scheme (e.g. `C99`, `C++14`) more
36+
than Python package versioning.
37+
38+
The frequency of releasing a new version of an API standard will likely be at
39+
regular intervals and on the order of one year, however no assumption on frequency of new versions appearing must be made.

0 commit comments

Comments
 (0)