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 publiclythe exact wording or contents of any exception message emitted
the exact structure or contents of any object
repr
sthe 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 objectregret.bar.Baz
, the presence ofBaz
is not public withinfoo
, only withinbar
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.