mirror of
https://github.com/valitydev/salt.git
synced 2024-11-07 00:55:19 +00:00
56 lines
2.7 KiB
ReStructuredText
56 lines
2.7 KiB
ReStructuredText
================
|
|
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.warn_until
|
|
<salt.utils.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.warn_until
|
|
<salt.utils.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.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.
|