Merge "Add support for a deprecated version"

oslo_config/cfg.py

@@ -662,6 +662,10 @@ class Opt(object):
     :param deprecated_reason: indicates why this opt is planned for removal in
                               a future release. Silently ignored if
                               deprecated_for_removal is False
+    :param deprecated_since: indicates which release this opt was deprecated
+                             in. Accepts any string, though valid version
+                             strings are encouraged. Silently ignored if
+                             deprecated_for_removal is False
     :param mutable: True if this option may be reloaded
 
     An Opt object has no public methods, but has a number of public properties:
@@ -722,6 +726,9 @@ class Opt(object):
 
     .. versionchanged:: 3.5
        Added *mutable* parameter.
+
+    .. versionchanged:: 3.12
+       Added *deprecated_since* parameter.
     """
     multi = False
 
@@ -731,7 +738,7 @@ class Opt(object):
                  deprecated_name=None, deprecated_group=None,
                  deprecated_opts=None, sample_default=None,
                  deprecated_for_removal=False, deprecated_reason=None,
-                 mutable=False):
+                 deprecated_since=None, mutable=False):
         if name.startswith('_'):
             raise ValueError('illegal name %s with prefix _' % (name,))
         self.name = name
@@ -757,6 +764,7 @@ class Opt(object):
         self.required = required
         self.deprecated_for_removal = deprecated_for_removal
         self.deprecated_reason = deprecated_reason
+        self.deprecated_since = deprecated_since
         self._logged_deprecation = False
         if deprecated_name is not None:
             deprecated_name = deprecated_name.replace('-', '_')

oslo_config/generator.py

@@ -247,8 +247,14 @@ class _OptFormatter(object):
                          (d.group or group_name, d.name or opt.dest))
 
         if opt.deprecated_for_removal:
+            if opt.deprecated_since:
+                lines.append(
+                    '# This option is deprecated for removal since %s.\n' % (
+                        opt.deprecated_since))
+            else:
+                lines.append(
+                    '# This option is deprecated for removal.\n')
             lines.append(
-                '# This option is deprecated for removal.\n'
                 '# Its value may be silently ignored in the future.\n')
             if opt.deprecated_reason:
                 lines.extend(

oslo_config/sphinxext.py

@@ -161,7 +161,11 @@ def _format_group(app, namespace, group_name, group_obj, opt_list):
                 yield _indent(line)
         if opt.deprecated_for_removal:
             yield _indent('.. warning::')
-            yield _indent('   This option is deprecated for removal.')
+            if opt.deprecated_since:
+                yield _indent('   This option is deprecated for removal '
+                              'since %s.' % opt.deprecated_since)
+            else:
+                yield _indent('   This option is deprecated for removal.')
             yield _indent('   Its value may be silently ignored ')
             yield _indent('   in the future.')
             yield ''

oslo_config/tests/test_generator.py

@@ -96,6 +96,10 @@ class GeneratorTestCase(base.BaseTestCase):
             deprecated_reason='This was supposed to work but it really, '
                               'really did not. Always buy house insurance.',
             help='DEPRECATED: Turn off stove'),
+        'deprecated_opt_with_deprecated_since': cfg.BoolOpt(
+            'tune_in',
+            deprecated_for_removal=True,
+            deprecated_since='13.0'),
         'deprecated_opt_with_deprecated_group': cfg.StrOpt(
             'bar', deprecated_name='foobar', deprecated_group='group1',
             help='deprecated'),

oslo_config/tests/test_sphinxext.py

@@ -290,11 +290,13 @@ class FormatGroupTest(base.BaseTestCase):
                 cfg.StrOpt('opt_name',
                            deprecated_for_removal=True,
                            deprecated_reason='because I said so',
+                           deprecated_since='13.0',
                            )
             ],
         )))
         self.assertIn('.. warning::', results)
         self.assertIn('because I said so', results)
+        self.assertIn('since 13.0', results)
 
     def test_mutable(self):
         results = '\n'.join(list(sphinxext._format_group(