saltstack/salt
1
0
Fork 0
mirror of https://github.com/saltstack/salt.git synced 2025-04-17 10:10:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

rework deprecation documentation for release names

Browse source 
Fixes #25827.
This commit is contained in:
Justin Findlay 2015-07-29 15:42:01 -06:00
parent d9ab4bb989
commit d377f42c48
1 changed files with 19 additions and 20 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
doc/topics/development/deprecations.rst
View file

@ -10,24 +10,24 @@ 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.
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.
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.
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 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.
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:
@ -36,14 +36,13 @@ Consider the following example:
def some_function(bar=False, foo=None):
if foo is not None:
salt.utils.warn_until(
(0, 18),
'Aluminum',
'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.
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.