|
| 1 | +(future-API-evolution)= |
| 2 | + |
1 | 3 | # Future API standard evolution
|
2 | 4 |
|
3 | 5 | ## Scope extensions
|
4 | 6 |
|
| 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 | +``` |
5 | 17 |
|
6 | 18 |
|
7 | 19 | ## Backwards compatibility
|
8 | 20 |
|
| 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. |
9 | 26 |
|
| 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. |
10 | 30 |
|
11 |
| -## Versioning |
12 | 31 |
|
| 32 | +(api-versioning)= |
| 33 | + |
| 34 | +## Versioning |
13 | 35 |
|
| 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