From 70898d7d857c03f1962617bf86cdc3ed0d9db921 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Sun, 13 Sep 2020 20:33:57 +0100 Subject: [PATCH 1/3] Add versioning section to "future API standard evolution" --- spec/future_API_evolution.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/spec/future_API_evolution.md b/spec/future_API_evolution.md index 0c538d8af..1bc1f1c98 100644 --- a/spec/future_API_evolution.md +++ b/spec/future_API_evolution.md @@ -10,4 +10,30 @@ ## Versioning - +This API standard uses the following versioning scheme: + +- The version is date-based, in the form `yyyy.mm` (e.g., `2020.12`). +- The version shall not include a standard way to do `alpha`/`beta`/`rc` or + `.post`/`.dev` type versions. + _Rationale: that's for Python packages, not for a standard._ +- The version must be made available at runtime via an attribute + `__array_api_version__` by a compliant implementation, in `'yyyy.mm'` format + as a string, in the namespace that implements the API standard. + _Rationale: dunder version strings are the standard way of doing this._ + +No utilities for dealing with version comparisons need to be provided; given +the format simple string comparisons with Python operators (`=-`, `<`, `>=`, +etc.) will be enough. + +.. note:: + + Rationale for the `yyyy.mm` versioning scheme choice: + the API will be provided as part of a library, which already has a versioning + scheme (typically PEP 440 compliant and in the form `major.minor.bugfix`), + and a way to access it via `module.__version__`. The API standard version is + completely independent from the package version. Given the standardization + process, it resembles a C/C++ versioning scheme (e.g. `C99`, `C++14`) more + than Python package versioning. + +The frequency of releasing a new version of an API standard will likely be at +regular intervals and on the order of one year, however no assumption on frequency of new versions appearing must be made. From 300c5acbd203830f9c259c0424f7805d5e4e2cab Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Sun, 13 Sep 2020 20:40:54 +0100 Subject: [PATCH 2/3] Add section on backwards compatibility --- spec/future_API_evolution.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/spec/future_API_evolution.md b/spec/future_API_evolution.md index 1bc1f1c98..526a25bad 100644 --- a/spec/future_API_evolution.md +++ b/spec/future_API_evolution.md @@ -6,6 +6,14 @@ ## Backwards compatibility +Functions, objects, keywords and specified behaviour are added to this API standard +only if those are already present in multiple existing array libraries, and if there is +data that those APIs are used. Therefore it is highly unlikely that future versions +of this standard will make backwards-incompatible changes. + +The aim is for future versions to be 100% backwards compatible with older versions. +Any exceptions must have strong rationales, and be clearly documented in the updated +API specification. ## Versioning From 974473114951fe9f99d6e95f9478d704a622b249 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Sun, 13 Sep 2020 20:49:31 +0100 Subject: [PATCH 3/3] Add scope extensions section to "future API standard evolution" --- spec/future_API_evolution.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/spec/future_API_evolution.md b/spec/future_API_evolution.md index 526a25bad..a173d1d11 100644 --- a/spec/future_API_evolution.md +++ b/spec/future_API_evolution.md @@ -2,6 +2,16 @@ ## Scope extensions +Proposals for scope extensions in a future version of the API standard will follow +the process documented at: + +TODO: link to specific document in https://github.com/data-apis/governance once +it is available. + +In summary, proposed new APIs go through several maturity stages, and will only be +accepted in a future version of this API standard once they have reached the "Final" +maturity stage, which means multiple array libraries have compliant implementations +and real-world experience from use of those implementations is available. ## Backwards compatibility