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 <sfinucan@redhat.com>

1 files changed, 12 insertions, 0 deletions

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