mirror of
https://github.com/valitydev/salt.git
synced 2024-11-07 08:58:59 +00:00
50 lines
2.4 KiB
ReStructuredText
50 lines
2.4 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.
|
|
|
|
Depending on the complexity and usage of a specific piece of code, the
|
|
deprecation time frame should be properly evaluated. As an example, a
|
|
deprecation warning which is shown for 2 major releases, for example `0.17.0`
|
|
and `2014.1.0`, gives users enough time to stop using the deprecated code and
|
|
adapt to the new one.
|
|
|
|
For example, if you're deprecating the usage of a keyword argument to a
|
|
function, that specific keyword argument should remain in place for the full
|
|
deprecation time frame and if that keyword argument is used, a deprecation
|
|
warning should be shown to the user.
|
|
|
|
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 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(
|
|
(0, 18),
|
|
'The \'foo\' argument has been deprecated and its '
|
|
'functionality removed, as such, its usage is no longer '
|
|
'required.'
|
|
)
|
|
|
|
Consider that the current salt release is ``0.16.0``. Whenever ``foo`` is
|
|
passed a value different from ``None`` that warning will be shown to the user.
|
|
This will happen in versions ``0.16.2`` to ``2014.1.0``, after which a
|
|
:py:exc:`RuntimeError` will be raised making us aware that the deprecated code
|
|
should now be removed.
|