From 16840b6a3f85a070a8f600b09db580c5ccd215a0 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Thu, 10 Dec 2020 21:48:17 +0000 Subject: Add documentation parameters for DeprecatedRule Currently, the way you replace a rule with another rule is by using the 'deprecated_rule' parameter of '(Documented)RuleDefault'. For example: deprecated_rule = policy.DeprecatedRule( name='foo:bar', check_str='role:bazz' ) policy.RuleDefault( name='foo:create_bar', check_str='role:bang', description='Create a bar.', deprecated_rule=deprecated_rule, deprecated_reason='foo:bar has been replaced by foo:create_bar', deprecated_since='N', ) In this instance, we're stating that the 'foo:create_bar' policy replaces the 'foo:bar' policy and we've used (and indeed have to use, to avoid a 'ValueError') the 'deprecated_reason' and 'deprecated_since' parameters on the **new** rule to illustrate why. This is confusing. The new rule clearly isn't the one that's deprecated, so why are we stating the 'deprecated_reason' and 'deprecated_since' there? We can clarify this by instead specifying the reason and timeline on the deprecated rule, like so: deprecated_rule = policy.DeprecatedRule( name='foo:bar', check_str='role:bazz' deprecated_reason='foo:bar has been replaced by foo:create_bar', deprecated_since='N', ) policy.RuleDefault( name='foo:create_bar', check_str='role:bang', description='Create a bar.', deprecated_rule=deprecated_rule, ) Add support for this, with appropriate warnings to nudge people over to the new, improved way of doing things eventually. Change-Id: Ie4809c7749242bd092a2677b7545ef281735d984 Signed-off-by: Stephen Finucane --- ...precated-metadata-to-DeprecatedRule-79d2e8a3f5d11743.yaml | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 releasenotes/notes/add-deprecated-metadata-to-DeprecatedRule-79d2e8a3f5d11743.yaml (limited to 'releasenotes') diff --git a/releasenotes/notes/add-deprecated-metadata-to-DeprecatedRule-79d2e8a3f5d11743.yaml b/releasenotes/notes/add-deprecated-metadata-to-DeprecatedRule-79d2e8a3f5d11743.yaml new file mode 100644 index 0000000..4d5c484 --- /dev/null +++ b/releasenotes/notes/add-deprecated-metadata-to-DeprecatedRule-79d2e8a3f5d11743.yaml @@ -0,0 +1,12 @@ +--- +features: + - | + ``DeprecatedRule`` now accepts two new parameters: ``deprecated_reason`` + and ``deprecated_since``. These should be used in place of the equivalent + parameters on the rule that is replacing this rule in order to avoid + confusion. +upgrade: + - | + Users with a ``RuleDefault`` or ``DocumentedRuleDefault`` that have + configured a ``deprecated_rule`` should move the ``deprecated_reason`` + and ``deprecated_since`` parameters to this ``DeprecatedRule``. -- cgit v1.2.1