Deprecate the ironic CLI

The 'ironic' CLI is being deprecated; it is slated for removal in the S*
release cycle. The 'openstack baremetal' CLI should be used instead.
A message is printed out to that effect and the documentation is
updated to reflect this.

Change-Id: Ie6ac3c6222ec6a6231b9a9cb2949cac56b48967f
Closes-Bug: 1700815

7 files changed, 31 insertions, 7 deletions

diff --git a/README.rst b/README.rst
index a85b9b8..54157a3 100644
--- a/README.rst
+++ b/README.rst
@@ -14,7 +14,8 @@ This is a client for the OpenStack `Ironic
 <https://wiki.openstack.org/wiki/Ironic>`_ API. It provides:
 
 * a Python API: the ``ironicclient`` module, and
-* two command-line interfaces: ``openstack baremetal`` and ``ironic``.
+* two command-line interfaces: ``openstack baremetal`` and ``ironic``
+  (deprecated, please use ``openstack baremetal``).
 
 Development takes place via the usual OpenStack processes as outlined in the
 `developer guide <https://docs.openstack.org/infra/manual/developers.html>`_.
@@ -74,8 +75,11 @@ the subcommands available, run::
 
     $ openstack help baremetal
 
-``ironic`` CLI
---------------
+``ironic`` CLI (deprecated)
+---------------------------
+
+This is deprecated and will be removed in the S* release. Please use the
+``openstack baremetal`` CLI instead.
 
 This package will install the ``ironic`` command line interface that you
 can use to interact with the ``ironic`` API.
diff --git a/doc/source/cli/ironic_client.rst b/doc/source/cli/ironic_client.rst
index 7a4dad5..81b5a9d 100644
--- a/doc/source/cli/ironic_client.rst
+++ b/doc/source/cli/ironic_client.rst
@@ -18,6 +18,12 @@ SYNOPSIS
 DESCRIPTION
 ===========
 
+.. WARNING::
+
+    The :program:`ironic` command-line interface is deprecated; no new features
+    will be added. This CLI will be removed in the S* release. The `openstack
+    baremetal <osc_plugin_cli>`_ command-line interface should be used instead.
+
 The :program:`ironic` command-line interface (CLI) interacts with the
 OpenStack Bare Metal Service (Ironic).
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
index aca6ce0..8647313 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -5,7 +5,8 @@ Python Bindings to the OpenStack Ironic API
 This is a client for the OpenStack `Ironic`_ API. It provides:
 
 * a Python API: the ``ironicclient`` module, and
-* two command-line interfaces: ``openstack baremetal`` and ``ironic``.
+* two command-line interfaces: ``openstack baremetal`` and ``ironic``
+  (deprecated, please use ``openstack baremetal`` instead).
 
 Contents
 ========
diff --git a/doc/source/user/create_command.rst b/doc/source/user/create_command.rst
index 486afb2..ed5fe3d 100644
--- a/doc/source/user/create_command.rst
+++ b/doc/source/user/create_command.rst
@@ -17,9 +17,12 @@ or YAML format. It can be done in one of three ways:
       <file>      File (.yaml or .json) containing descriptions of the
                   resources to create. Can be specified multiple times.
 
-2. Using ironic CLI's ``ironic create`` command::
+2. Using ironic CLI's ``ironic create`` command (deprecated, please use
+   ``openstack baremetal create`` instead)::
 
     $ ironic help create
+    The "ironic" CLI is deprecated and will be removed in the S* release.
+    Please use the "openstack baremetal" CLI instead.
     usage: ironic create <file> [<file> ...]
 
     Create baremetal resources (chassis, nodes, port groups and ports). The
diff --git a/ironicclient/shell.py b/ironicclient/shell.py
index df7c54f..25676f1 100644
--- a/ironicclient/shell.py
+++ b/ironicclient/shell.py
@@ -333,6 +333,10 @@ class IronicShell(object):
             return (api_major_version, os_ironic_api_version)
 
     def main(self, argv):
+        # TODO(rloo): delete the ironic CLI in the S* cycle.
+        print('The "ironic" CLI is deprecated and will be removed in the '
+              'S* release. Please use the "openstack baremetal" CLI instead.',
+              file=sys.stderr)
         # Parse args once to find version
         parser = self.get_base_parser()
         (options, args) = parser.parse_known_args(argv)
diff --git a/ironicclient/tests/unit/test_shell.py b/ironicclient/tests/unit/test_shell.py
index 77a2f19..29865a7 100644
--- a/ironicclient/tests/unit/test_shell.py
+++ b/ironicclient/tests/unit/test_shell.py
@@ -249,10 +249,10 @@ class ShellTest(utils.BaseTestCase):
 
     def test_ironic_api_version(self):
         err = self.shell('--ironic-api-version 1.2 help')[1]
-        self.assertFalse(err)
+        self.assertIn('The "ironic" CLI is deprecated', err)
 
         err = self.shell('--ironic-api-version latest help')[1]
-        self.assertFalse(err)
+        self.assertIn('The "ironic" CLI is deprecated', err)
 
         self.assertRaises(exc.CommandError,
                           self.shell, '--ironic-api-version 1.2.1 help')
@@ -264,6 +264,7 @@ class ShellTest(utils.BaseTestCase):
     def test_warning_on_no_version(self):
         err = self.shell('help')[1]
         self.assertIn('You are using the default API version', err)
+        self.assertIn('The "ironic" CLI is deprecated', err)
 
 
 class TestCase(testtools.TestCase):
diff --git a/releasenotes/notes/deprecate-ironic-cli-686b7a238ddf3e25.yaml b/releasenotes/notes/deprecate-ironic-cli-686b7a238ddf3e25.yaml
new file mode 100644
index 0000000..0b211b0
--- /dev/null
+++ b/releasenotes/notes/deprecate-ironic-cli-686b7a238ddf3e25.yaml
@@ -0,0 +1,5 @@
+---
+deprecations:
+  - |
+    The ``ironic`` CLI has been deprecated and will be removed in the
+    S* release.  Please use the ``openstack baremetal`` CLI instead.