Deprecation#
Please note this policy is not currently in force. We aim to restore deprecation for V0.5 but the policy may be revised, but it will be based on the below.
Deprecation policy#
aeon releases follow semantic versioning. A release number denotes <major>.<minor>.<patch> versions.
Our previous deprecation policy is as follows:
all interface breaking (not downwards compatible) changes to public interfaces must
be accompanied by deprecation. * such changes or removals happen only at MINOR or MAJOR versions, not at PATCH versions. * deprecation warnings should be included for at least one MINOR version cycle before change or removal.
Deprecation process#
The deprecation process is as follows:
Raise a warning. For all deprecated functionality, we raise a
FutureWarning
. The warning message should give the version number when the functionality will be changed and describe the new usage.
* Add a TODO comment in the code. Add the following TODO comment to all pieces of code that can be removed: TODO: remove in <version-number>
. For example, TODO: remove in v0.11.0
. The TODO comment should describe which steps need to be taken for deprecation (e.g. removal of arguments, removal of functions or blocks of code). If changes need to be applied across multiple places, place multiple TODO comments.
* Remove deprecated functionality. As part of the release process, all deprecated functionality that is due to be removed will be removed by searching for the TODO comments.
To raise the warning, we use the deprecated package.
The package provides depreciation helper functions such as the deprecated
decorator.
When importing it from deprecated.sphinx
, it automatically adds a deprecation message to the docstring.
You can decorate functions, methods or classes.
Examples#
In the examples below, the deprecated
decorator will raise a FutureWarning
saying that the functionality has been deprecated since version 0.9.0 and will be removed in version 0.11.0.
Functions#
from deprecated.sphinx import deprecated
# TODO: remove in v0.7.0
@deprecated(version="0.6.0", reason="my_old_function will be removed in v0.7.0",
- category=FutureWarning)
- def my_old_function(x, y):
return x + y
Methods#
from deprecated.sphinx import deprecated
class MyClass:
# TODO: remove in v0.7.0
@deprecated(version="0..0", reason="my_old_method will be removed in v0.7.0",
- category=FutureWarning)
- def my_old_method(self, x, y):
return x + y
Classes#
from deprecated.sphinx import deprecated
# TODO: remove in v0.7.0
@deprecated(version="0.6.0", reason="MyOldClass will be removed in v0.7.0",
- category=FutureWarning)
- class MyOldClass:
pass
Special deprecations#
This section outlines the deprecation process for cases which use of deprecated
does not cover.