salt/doc/topics/development/deprecations.rst

================
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.