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, 21 insertions, 10 deletions

diff --git a/oslo_policy/generator.py b/oslo_policy/generator.py
index ac1a992..f2b6027 100644
--- a/oslo_policy/generator.py
+++ b/oslo_policy/generator.py
@@ -204,21 +204,32 @@ def _format_rule_default_yaml(default, include_help=True, comment_rule=True,
              'reason': _format_help_text(default.deprecated_reason),
              'text': text}
     elif add_deprecated_rules and default.deprecated_rule:
+        deprecated_reason = (
+            default.deprecated_rule.deprecated_reason or
+            default.deprecated_reason
+        )
+        deprecated_since = (
+            default.deprecated_rule.deprecated_since or
+            default.deprecated_since
+        )
+
         # This issues a deprecation warning but aliases the old policy name
         # with the new policy name for compatibility.
         deprecated_text = (
             '"%(old_name)s":"%(old_check_str)s" has been deprecated '
             'since %(since)s in favor of "%(name)s":"%(check_str)s".'
-        ) % {'old_name': default.deprecated_rule.name,
-             'old_check_str': default.deprecated_rule.check_str,
-             'since': default.deprecated_since,
-             'name': default.name,
-             'check_str': default.check_str,
-             }
-        text = ('%(text)s# DEPRECATED\n%(deprecated_text)s\n%(reason)s\n' %
-                {'text': text,
-                 'reason': _format_help_text(default.deprecated_reason),
-                 'deprecated_text': _format_help_text(deprecated_text)})
+        ) % {
+            'old_name': default.deprecated_rule.name,
+            'old_check_str': default.deprecated_rule.check_str,
+            'since': deprecated_since,
+            'name': default.name,
+            'check_str': default.check_str,
+        }
+        text = '%(text)s# DEPRECATED\n%(deprecated_text)s\n%(reason)s\n' % {
+            'text': text,
+            'reason': _format_help_text(deprecated_reason),
+            'deprecated_text': _format_help_text(deprecated_text)
+        }
 
         if default.name != default.deprecated_rule.name:
             text += ('"%(old_name)s": "rule:%(name)s"\n' %