From 5e461765404d3225a6c1c9c81b7e68e24299cc87 Mon Sep 17 00:00:00 2001
From: Dean Troyer <dtroyer@gmail.com>
Date: Fri, 20 Nov 2015 10:36:40 -0600
Subject: [PATCH] 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
---
 doc/source/command-wrappers.rst | 52 +++++++++++++++++++++++++++++++++
 doc/source/index.rst            |  1 +
 2 files changed, 53 insertions(+)
 create mode 100644 doc/source/command-wrappers.rst

diff --git a/doc/source/command-wrappers.rst b/doc/source/command-wrappers.rst
new file mode 100644
index 0000000000..b14eccdde8
--- /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 6b7d63f36e..255474721e 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -38,6 +38,7 @@ Developer Documentation
 
    developing
    command-options
+   command-wrappers
 
 Project Goals
 -------------