代码弃用¶

Salt应该保持向后兼容，虽然有时候由于一些特性和/或解决方案不在适用时这种兼容性可能会被破坏。开始时，开发者可能会想，看来没有任何地方用到了这段代码，所以删除它是安全的。然后，新版本发布后，用户就是开始埋怨他们正在使用的功能被删除了。这种情况应该避免，在这种情况下，代码应该被弃用。

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 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 salt.utils.warn_until will raise a 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.

请看下面的例子

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.