Define a feature depreciation policy

[alvarofpp]

Description

We must have a feature depreciation policy, something that allows us to deprecate code in a clear and objective way.

Topics and suggestions

• Use a warning log on the functions that will be deprecated.
• Define a number of versions between the warning and the code removal (e.g. remove code after 2 minor changes). Example: in a certain feature we set the warning at version 2.1.X and we remove it at change 2.3.0).
• Put everything that has been decided in a single document in the repository root.

[alvarofpp]

For this task, I am considering the following texts:

• How to Deprecate a PyPI Package
• PEP 387 – Backwards Compatibility Policy
• PEP 702 – Marking deprecations using the type system
• Semantic Versioning

[alvarofpp]

My proposal is:

• Only remove functions after version change in major;
• When it is decided that a feature will be deprecated, we will put an alert in its execution, with a message directing to the new feature and in which version that feature will be removed. Example:

from warnings import warn, DeprecationWarning

def a(self):
    warn('You should use the `b` function. The `a` function will be removed in version 3.x.x', DeprecationWarning)
    pass

def b(self):
    pass

Some links for the record:

• DeprecationWarning