Skip to content

Commit cc07b49

Browse files
committed
Add content for the "future API evolution" page
Also largely taken over from the array API standard, with changes for the process and the smaller scope.
1 parent fd91ea3 commit cc07b49

File tree

2 files changed

+53
-1
lines changed

2 files changed

+53
-1
lines changed

spec/API_specification/index.rst

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _api-specification:
2+
13
API specification
24
=================
35

spec/future_API_evolution.md

+51-1
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,63 @@
1+
(future-API-evolution)=
2+
13
# Future API standard evolution
24

35
## Scope extensions
46

7+
Proposals for scope extensions in a future version of the API standard will
8+
be proposed in an issue on the
9+
[data-apis/dataframe-api](https://github.com/data-apis/dataframe-api/issues)
10+
repository, and discussed in public and decided upon.
11+
12+
```{note}
13+
In the future, once the API standard matures, this may be changed and follow
14+
the more formal process documented at
15+
[data-apis/governance::process_document.md](https://github.com/data-apis/governance/blob/main/process_document.md).
16+
```
517

618

719
## Backwards compatibility
820

21+
Functions, objects, keywords and specified behavior are added to this API
22+
standard only if there is a clear need, and functionality is either very
23+
minimally scoped or are already present in multiple existing dataframe
24+
libraries. Therefore it is highly unlikely that future versions of this
25+
standard will make backwards-incompatible changes.
926

27+
The aim is for future versions to be 100% backwards compatible with older
28+
versions. Any exceptions must have strong rationales and be clearly documented
29+
in the updated API specification and Changelog for a release.
1030

11-
## Versioning
1231

32+
(api-versioning)=
33+
34+
## Versioning
1335

36+
This API standard uses the following versioning scheme:
37+
38+
- The version is date-based, in the form `yyyy.mm` (e.g., `2020.12`).
39+
- The version shall not include a standard way to do `alpha`/`beta`/`rc` or
40+
`.post`/`.dev` type versions.
41+
_Rationale: that's for Python packages, not for a standard._
42+
- The version must be made available at runtime via an attribute
43+
`__dataframe_api_version__` by a compliant implementation, in `'yyyy.mm'` format
44+
as a string, in the namespace that implements the API standard.
45+
_Rationale: dunder version strings are the standard way of doing this._
46+
47+
No utilities for dealing with version comparisons need to be provided; given
48+
the format simple string comparisons with Python operators (`=-`, `<`, `>=`,
49+
etc.) will be enough.
50+
51+
```{note}
52+
Rationale for the `yyyy.mm` versioning scheme choice:
53+
the API will be provided as part of a library, which already has a versioning
54+
scheme (typically PEP 440 compliant and in the form `major.minor.bugfix`),
55+
and a way to access it via `module.__version__`. The API standard version is
56+
completely independent from the package version. Given the standardization
57+
process, it resembles a C/C++ versioning scheme (e.g. `C99`, `C++14`) more
58+
than Python package versioning.
59+
```
60+
61+
The frequency of releasing a new version of an API standard will likely be at
62+
regular intervals and on the order of one year, however no assumption on
63+
frequency of new versions appearing must be made.

0 commit comments

Comments
 (0)