Deprecating a policy is confusing

Some oddities came up in IRC today as we were using DeprecatedRule to cover a test case in keystone [0].

The initial implementation of the DeprecatedRule object attempted to follow existing conventions used to deprecate configuration options in oslo.config, but there are some ways the we could improve the experience.

It can be confusing to see deprecated kwargs on the option that is not actually being deprecated. One way we could fix this would be to isolate all deprecated kwargs to the DeprecatedRule object instead of having to deal with setting deprecated kwargs on each object. So something like the following would be preferred:

deprecated_rule = policy.DeprecatedRule(
    name='foo:bar',
    check_str='role:bazz',
    deprecated_reason='foo:create_bar is more granular than foo:bar',
    deprecated_since='N'
)

policy.DocumentedRuleDefault(
    name='foo:create_bar',
    check_str='role:bang',
    description='Create a bar.',
    operations=[{'path': '/v1/bars', 'method': 'POST'}],
    deprecated_rule=deprecated_rule
)

instead of:

deprecated_rule = policy.DeprecatedRule(
    name='foo:bar',
    check_str='role:bazz'
)

policy.DocumentedRuleDefault(
    name='foo:create_bar',
    check_str='role:bang',
    description='Create a bar.',
    operations=[{'path': '/v1/bars', 'method': 'POST'}],
    deprecated_rule=deprecated_rule,
    deprecated_reason='foo:create_bar is more granular than foo:bar',
    deprecated_since='N'
)

[0] http://eavesdrop.openstack.org/irclogs/%23openstack-keystone/%23openstack-keystone.2018-06-27.log.html#t2018-06-27T15:46:58