Add command wrapper doc

This is a follow-up to I6c750730963615895f5d9953487d2d5a905885a8 that
removed a command deprecation warning wrapper.  This documents the
technique for later use.

Change-Id: Ieaa1e6b7eed4e5b037b4bfb6cf488e1290fc69f7

2 files changed, 53 insertions, 0 deletions

diff --git a/doc/source/command-wrappers.rst b/doc/source/command-wrappers.rst
new file mode 100644
index 00000000..b14eccdd
--- /dev/null
+++ b/doc/source/command-wrappers.rst
@@ -0,0 +1,52 @@
+======================
+Command Class Wrappers
+======================
+
+When we want to deprecate a command, policy says we need to alert the user.
+We do this with a message logged at WARNING level before any command output
+is emitted.
+
+OpenStackClient command classes are derived from the ``cliff`` classes.
+Cliff uses ``setuptools`` entry points for dispatching the parsed command
+to the respective handler classes.  This lends itself to modifying the
+command execution at run-time.
+
+The obvious approach to adding the deprecation message would be to just add
+the message to the command class ``take_action()`` method directly.  But then
+the various deprecations are scattered throughout the code base.  If we
+instead wrap the deprecated command class with a new class we can put all of
+the wrappers into a separate, dedicated module.  This also lets us leave the
+original class unmodified and puts all of the deprecation bits in one place.
+
+This is an example of a minimal wrapper around a command class that logs a
+deprecation message as a warning to the user then calls the original class.
+
+* Subclass the deprecated command.
+
+* Set class attribute ``deprecated`` to ``True`` to signal cliff to not
+  emit help text for this command.
+
+* Log the deprecation message at WARNING level and refer to the replacement
+  for the deprecated command in the log warning message.
+
+* Change the entry point class in ``setup.cfg`` to point to the new class.
+
+Example Deprecation Class
+-------------------------
+
+.. code-block: python
+
+    class ListFooOld(ListFoo):
+        """List resources"""
+
+        # This notifies cliff to not display the help for this command
+        deprecated = True
+
+        log = logging.getLogger('deprecated')
+
+        def take_action(self, parsed_args):
+            self.log.warning(
+                "%s is deprecated, use 'foobar list'",
+                getattr(self, 'cmd_name', 'this command'),
+            )
+            return super(ListFooOld, self).take_action(parsed_args)
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 6b7d63f3..25547472 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -38,6 +38,7 @@ Developer Documentation
 
    developing
    command-options
+   command-wrappers
 
 Project Goals
 -------------