# Stability guarantees

## Stability of public API

This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Here's a very
short excerpt:

> Given a version number MAJOR.MINOR.PATCH, increment the:
> 
> - MAJOR version when you make incompatible API changes
> - MINOR version when you add functionality in a backward compatible manner
> - PATCH version when you make backward compatible bug fixes

In particular, given e.g. version `1.2.3` of the `presto` package, you can expect the following:

- We increase the *patch* version to e.g. `1.2.4` when we fix some bugs and/or improve performance
  without changes to our public API. Your measurement scripts do not require any modification and
  continue to work as expected.

- We increase the *minor* version to e.g. `1.3.0` when we introduce new functionality without
  breaking existing workflows. Your measurement scripts do not require any modification and
  continue to work as expected. However, you might want to revise them to make use of the new
  functionality if it applies to your use case.

- We increase the *major* version to e.g. `2.0.0` when we introduce new functionality and/or
  change/remove existing functionality in a way that might break existing workflows. Your
  measurement scripts are generally *not* expected to work without modifications, and might require
  changes as outlined in the release notes.

**Breaking changes are extremely rare**, and are clearly marked by a major release and documented
in the [changelog](CHANGELOG). We strive to provide a fearless update process where you can look
forward to a new update with excitement, without having to worry that your hand-crafted
measurements will suddenly stop working.

## Minimum supported version of dependencies

At a minimum, we follow the scientific Python ecosystem coordination (SPEC) guideline
[SPEC 0][spec0] to support Python versions for 3 years after their initial release, and core
dependencies for 2 years after their initial release.

At a maximum, we support Python versions for 5 years after their initial release or until they
reach their [end of life][pyver], and core dependencies for 3 years after their initial release.

Occasionally, we may drop support for a core-dependency version earlier than documented above. This
may happen e.g. if a newer version is needed due to a critical bug fix which is not backported to
older versions.

In any case, an increase in the minimum-supported Python version is documented in the
[CHANGELOG](CHANGELOG) and is accompanied by a bump of the *minor* version. For instance: 1.2.0 ->
1.3.0.

[pyver]: https://devguide.python.org/versions/
[spec0]: https://scientific-python.org/specs/spec-0000/