Deprecate keystone CLI

bp deprecate-cli

Change-Id: Ia0170afc1476e531b1348c1faee47cfa5886dd96

doc/source/index.rst

@@ -44,16 +44,13 @@ Kilo approved specs:
 
    specs/kilo/*
 
-.. NOTE(dhellmann): Uncomment this section after there is at least one
-   non-template spec for keystoneclient.
+Keystone client approved specs:
 
-   Keystone client approved specs:
+.. toctree::
+   :glob:
+   :maxdepth: 1
 
-   .. toctree::
-      :glob:
-      :maxdepth: 1
-
-      specs/keystoneclient/*
+   specs/keystoneclient/*
 
 
 Keystone middleware approved specs:

specs/keystoneclient/deprecate-cli.rst

@@ -0,0 +1,114 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+======================
+Deprecate keystone CLI
+======================
+
+`bp deprecate-cli
+<https://blueprints.launchpad.net/python-keystoneclient/+spec/deprecate-cli>`_
+
+
+The ``keystone`` CLI is superceded by the OpenStack unified CLI (OSC), so let's
+get rid of it as soon as we can.
+
+
+Problem Description
+===================
+
+The ``keystone`` CLI is superceded by OSC, as such it's a waste for us to
+continue maintaining it. Since we can't just delete it we need to deprecate it
+first.
+
+Proposed Change
+===============
+
+The ``keystone`` CLI will print out Python's usual deprecation warning message
+when it's run. By using Python's regular warnings module users can disable the
+warning message, see https://docs.python.org/2/using/cmdline.html#cmdoption-W
+
+The help text (``keystone --help``) will be updated to also say that the
+command is deprecated.
+
+This is part of a larger effort to get rid of the ``keystone`` command for
+good.
+
+Alternatives
+------------
+
+a) Engage in a major effort to fully support the ``keystone`` command,
+   including implement all the identity V3 commands, duplicating the work of
+   the OSC.
+
+b) Make ``keystone`` a wrapper around the OSC.
+
+Security Impact
+---------------
+
+The ``keystone`` CLI will only be patched for security and critical fixes since
+it's deprecated.
+
+Notifications Impact
+--------------------
+
+None. Notifications don't use the ``keystone`` CLI.
+
+Other End User Impact
+---------------------
+
+Users will see a message every time unless they use -W to disable the warnings.
+
+Performance Impact
+------------------
+
+None.
+
+Other Deployer Impact
+---------------------
+
+Deployers will eventually need to move to using the unified CLI.
+
+Developer Impact
+----------------
+
+Developers will need to move to using the unified CLI.
+
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  <blk-u> Brant Knudson
+
+Work Items
+----------
+
+* Change ``keystone`` CLI to print the deprecation warning when run.
+* Change ``keystone`` help text to print that it's deprecated.
+* Change ``keystone`` man page to say that it's deprecated.
+
+
+Dependencies
+============
+
+None.
+
+Documentation Impact
+====================
+
+The documentation should change all ``keystone`` commands to the equivalent
+``openstack`` command.
+
+
+References
+==========
+
+* https://docs.python.org/2/using/cmdline.html#cmdoption-W
+
+* http://docs.openstack.org/developer/python-openstackclient/