regret’s Deprecation Policy#

This document is regret’s own deprecation policy.

It attempts to define, with as much forethought as is known, how backwards-incompatible changes to the library will be performed.

Public API#

regret’s public API broadly follows what is often intuitively or culturally understood in the Python ecosystem. Here though is a more precise (though potentially still incomplete) description of things not considered part of its public API:

  • any object whose name follows Python’s “private” convention (starting with an underscore)

  • the entire contents of any module named in the above way (with a leading underscore)

  • the contents of the regret.tests package, i.e. the test suite, even if objects “appear” to be named publicly

  • the exact wording or contents of any exception message emitted

  • the exact structure or contents of any object reprs

  • the subclassability (i.e. ability of a class to be a superclass of another) of any object not explicitly marked as subclassable

  • any “transitive” imported objects – meaning, if a module regret.foo imports an object regret.bar.Baz, the presence of Baz is not public within foo, only within bar

Versioning#

With the above public API in mind, regret attempts to follow the Semantic Versioning specification as an (imperfect) communication mechanism. Specifically, major version numbers will be bumped for each backwards incompatible change, including changes which have been through the deprecation period discussed below.

Backwards Incompatible Changes#

In accordance with the semantic Versioning scheme mentioned in this document, regret’s public API may change more drastically until it reaches version 1.0.0 (it’s “official” public release).

In the event that an API requires a backwards incompatible change, a deprecation period of six months or two releases will preserve the original behavior unchanged, whilst emitting a DeprecationWarning, and introducing any replacement APIs.

Python Version Support#

In general, regret’s support for particular versions of Python will end at latest on or around the end of life dates for each respective version, but more typically once they constitute a meaningful maintenance burden and constitute a smaller proportion of installations. Exceptions may be made in some circumstances where versions see continued use, but should not be relied upon. Support contracts are available for situations which require them.

Unless otherwise noted, only the latest patch version of each CPython release is officially supported.

Attempts will always be made to have regret’s supported Python versions reflected in its built distributions (i.e. via python_requires), such that installation tools do not install versions unless they are compatible with the running interpreter.

Further Notes#

regret’s continuous integration and test suite should be referenced as a representation of execution “environments” it supports.

This includes both operating system support, as well as broader concerns – as a hypothetical example, if a new way of installing or running regret is used which is not already being tested in the automated suite, its support or continuing function is not guaranteed.

Pull requests are welcome to add additional supported environments, though some discretion may still be applied if there is likelihood of ongoing maintenance burden.