Skip to content

Add section on future API standard evolution #37

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 16, 2020
Merged

Add section on future API standard evolution #37

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
70898d7
Add versioning section to "future API standard evolution"
rgommers Sep 13, 2020
300c5ac
Add section on backwards compatibility
rgommers Sep 13, 2020
9744731
Add scope extensions section to "future API standard evolution"
rgommers Sep 13, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 45 additions & 1 deletion spec/future_API_evolution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,56 @@

## 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

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

## 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.