mirror of
https://github.com/valitydev/salt.git
synced 2024-11-07 17:09:03 +00:00
2b76029ded
This moves the following functions from salt.utils to salt.utils.versions: - warn_until - kwargs_warn_until - compare_versions (as salt.utils.versions.compare) - version_cmp
58 lines
2.8 KiB
ReStructuredText
58 lines
2.8 KiB
ReStructuredText
.. _deprecations:
|
|
|
|
================
|
|
Deprecating Code
|
|
================
|
|
|
|
Salt should remain backwards compatible, though sometimes, this backwards
|
|
compatibility needs to be broken because a specific feature and/or solution is
|
|
no longer necessary or required. At first one might think, let me change this
|
|
code, it seems that it's not used anywhere else so it should be safe to remove.
|
|
Then, once there's a new release, users complain about functionality which was
|
|
removed and they where using it, etc. This should, at all costs, be avoided,
|
|
and, in these cases, *that* specific code should be deprecated.
|
|
|
|
In order to give users enough time to migrate from the old code behavior to the
|
|
new behavior, the deprecation time frame should be carefully determined based
|
|
on the significance and complexity of the changes required by the user.
|
|
|
|
Salt feature releases are based on the Periodic Table. Any new features going
|
|
into the develop branch will be named after the next element in the Periodic
|
|
Table. For example, Beryllium was the feature release name of the develop
|
|
branch before the 2015.8 branch was tagged. At that point in time, any new
|
|
features going into the develop branch after 2015.8 was branched were part of
|
|
the Boron feature release.
|
|
|
|
A deprecation warning should be in place for at least two major releases before
|
|
the deprecated code and its accompanying deprecation warning are removed. More
|
|
time should be given for more complex changes. For example, if the current
|
|
release under development is ``Sodium``, the deprecated code and associated
|
|
warnings should remain in place and warn for at least ``Aluminum``.
|
|
|
|
To help in this deprecation task, salt provides
|
|
:func:`salt.utils.versions.warn_until <salt.utils.versions.warn_until>`. The
|
|
idea behind this helper function is to show the deprecation warning to the user
|
|
until salt reaches the provided version. Once that provided version is equaled
|
|
:func:`salt.utils.versions.warn_until <salt.utils.versions.warn_until>` will
|
|
raise a :py:exc:`RuntimeError` making salt stop its execution. This stoppage is
|
|
unpleasant and will remind the developer that the deprecation limit has been
|
|
reached and that the code can then be safely removed.
|
|
|
|
Consider the following example:
|
|
|
|
.. code-block:: python
|
|
|
|
def some_function(bar=False, foo=None):
|
|
if foo is not None:
|
|
salt.utils.versions.warn_until(
|
|
'Aluminum',
|
|
'The \'foo\' argument has been deprecated and its '
|
|
'functionality removed, as such, its usage is no longer '
|
|
'required.'
|
|
)
|
|
|
|
Development begins on the ``Aluminum`` release when the ``Magnesium`` branch is
|
|
forked from the develop branch. Once this occurs, all uses of the
|
|
``warn_until`` function targeting ``Aluminum``, along with the code they are
|
|
warning about should be removed from the code.
|