add deprecation_reason to log message

When we log the warning that an option is deprecated for removal,
include the reason if we have one. Previously the deprecation reason was
only visible in the sample configuration file.

Add some tests for the log messages emitted when deprecated options are
used.

Change-Id: I5e309a3651041580fdf529ff31e18bbd90714f35
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

oslo_config/cfg.py

@@ -955,10 +955,16 @@ class Opt(object):
         if self.deprecated_for_removal and not self._logged_deprecation:
             self._logged_deprecation = True
             pretty_group = group_name or 'DEFAULT'
+            if self.deprecated_reason:
+                pretty_reason = ' ({})'.format(self.deprecated_reason)
+            else:
+                pretty_reason = ''
             LOG.warning('Option "%(option)s" from group "%(group)s" is '
-                        'deprecated for removal.  Its value may be '
+                        'deprecated for removal%(reason)s.  Its value may be '
                         'silently ignored in the future.',
-                        {'option': self.dest, 'group': pretty_group})
+                        {'option': self.dest,
+                         'group': pretty_group,
+                         'reason': pretty_reason})
         return value
 
     def _add_to_cli(self, parser, group=None):

oslo_config/tests/test_cfg.py

@@ -15,6 +15,7 @@
 import argparse
 import errno
 import functools
+import logging
 import os
 import shutil
 import sys
@@ -913,6 +914,16 @@ class PositionalTestCase(BaseTestCase):
 
 class ConfigFileOptsTestCase(BaseTestCase):
 
+    def setUp(self):
+        super(ConfigFileOptsTestCase, self).setUp()
+        self.logger = self.useFixture(
+            fixtures.FakeLogger(
+                format='%(message)s',
+                level=logging.WARNING,
+                nuke_handlers=True,
+            )
+        )
+
     def _do_deprecated_test(self, opt_class, value, result, key,
                             section='DEFAULT',
                             dname=None, dgroup=None):
@@ -1010,9 +1021,42 @@ class ConfigFileOptsTestCase(BaseTestCase):
                    '--config-file', paths[1]])
 
         self.assertTrue(hasattr(self.conf, 'newfoo'))
-        # TODO(mtreinish): Add a check for the log message
         self.assertTrue(hasattr(self.conf, 'oldfoo'))
         self.assertEqual('last', self.conf.newfoo)
+        log_out = self.logger.output
+        self.assertIn('is deprecated', log_out)
+        self.assertIn('Use option "newfoo"', log_out)
+
+    def test_use_deprecated_for_removal_without_reason(self):
+        self.conf.register_cli_opt(
+            cfg.StrOpt('oldfoo',
+                       deprecated_for_removal=True))
+
+        paths = self.create_tempfiles([('0',
+                                        '[DEFAULT]\n'
+                                        'oldfoo = middle\n')])
+
+        self.conf(['--oldfoo', 'first',
+                   '--config-file', paths[0]])
+
+        log_out = self.logger.output
+        self.assertIn('deprecated for removal.', log_out)
+
+    def test_use_deprecated_for_removal_with_reason(self):
+        self.conf.register_cli_opt(
+            cfg.StrOpt('oldfoo',
+                       deprecated_for_removal=True,
+                       deprecated_reason='a very good reason'))
+
+        paths = self.create_tempfiles([('0',
+                                        '[DEFAULT]\n'
+                                        'oldfoo = middle\n')])
+
+        self.conf(['--oldfoo', 'first',
+                   '--config-file', paths[0]])
+
+        log_out = self.logger.output
+        self.assertIn('deprecated for removal (a very good reason).', log_out)
 
     def test_conf_file_str_use_dname(self):
         self._do_dname_test_use(cfg.StrOpt, 'value1', 'value1')

releasenotes/notes/show-deprecated-reason-361a8eb31e05c97e.yaml

@@ -0,0 +1,5 @@
+---
+features:
+  - |
+    When a deprecated option is used, the message warning that the option is
+    deprecated now includes the reason for the deprecation, if there is one given.