Skip to content

Commit

Permalink
Add content for the "future API evolution" page
Browse files Browse the repository at this point in the history
Also largely taken over from the array API standard, with changes
for the process and the smaller scope.
  • Loading branch information
rgommers committed May 3, 2023
1 parent fd91ea3 commit cc07b49
Show file tree
Hide file tree
Showing 2 changed files with 53 additions and 1 deletion.
2 changes: 2 additions & 0 deletions spec/API_specification/index.rst
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _api-specification:

API specification
=================

Expand Down
52 changes: 51 additions & 1 deletion spec/future_API_evolution.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,63 @@
(future-API-evolution)=

# Future API standard evolution

## Scope extensions

Proposals for scope extensions in a future version of the API standard will
be proposed in an issue on the
[data-apis/dataframe-api](https://github.com/data-apis/dataframe-api/issues)
repository, and discussed in public and decided upon.

```{note}
In the future, once the API standard matures, this may be changed and follow
the more formal process documented at
[data-apis/governance::process_document.md](https://github.com/data-apis/governance/blob/main/process_document.md).
```


## Backwards compatibility

Functions, objects, keywords and specified behavior are added to this API
standard only if there is a clear need, and functionality is either very
minimally scoped or are already present in multiple existing dataframe
libraries. 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 and Changelog for a release.

## Versioning

(api-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
`__dataframe_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.

0 comments on commit cc07b49

Please sign in to comment.