Add oslopolicy-convert-json-to-yaml tool

Add ``oslopolicy-convert-json-to-yaml`` tool which can be
used to convert the json formatted policy file to yaml format.
It takes json formatted policy file as input and convert it to
a yaml formatted policy file similar to 'oslopolicy-sample-generator'
tool except keeping the overridden rule as uncommented.

This tool does the following:

* Comment out any rules that match the default from policy-in-code.
* Keep rules uncommented if rule is overridden.
* Does not auto add the deprecated rules in the file unless it not already
  present in the file.
* Keep any extra rules or already exist deprecated rules uncommented
  but at the end of the file with a warning text.

I did not add the new functionality in existing 'oslopolicy-policy-upgrade'
tool because the above listed features of new tool end up creating a
complete different code path instead of reusing it from existing tool so it
better to have separate tool which can be removed in future once all deployments
are migrated to YAML formatted file.

This commits add doc and reno also for this tool

Partial implement blueprint policy-json-to-yaml

Change-Id: Icc245951b2992cc09a891516ffd14f3d4c009920

3 files changed, 94 insertions, 0 deletions

diff --git a/doc/source/cli/common/convert-opts.rst b/doc/source/cli/common/convert-opts.rst
new file mode 100644
index 0000000..c7f69b6
--- /dev/null
+++ b/doc/source/cli/common/convert-opts.rst
@@ -0,0 +1,8 @@
+.. option:: --namespace NAMESPACE
+
+    Option namespace(s) under "oslo.policy.policies" in which to query for
+    options.
+
+.. option:: --policy-file POLICY_FILE
+
+    Path to the policy file which need to be converted to ``yaml`` format.
diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst
index b8e54d8..500a7fe 100644
--- a/doc/source/cli/index.rst
+++ b/doc/source/cli/index.rst
@@ -13,3 +13,4 @@ This document describes the various command line tools exposed by
    oslopolicy-list-redundant
    oslopolicy-policy-generator
    oslopolicy-sample-generator
+   oslopolicy-convert-json-to-yaml
diff --git a/doc/source/cli/oslopolicy-convert-json-to-yaml.rst b/doc/source/cli/oslopolicy-convert-json-to-yaml.rst
new file mode 100644
index 0000000..1689aed
--- /dev/null
+++ b/doc/source/cli/oslopolicy-convert-json-to-yaml.rst
@@ -0,0 +1,85 @@
+===============================
+oslopolicy-convert-json-to-yaml
+===============================
+
+.. program:: oslopolicy-convert-json-to-yaml
+
+Synopsis
+--------
+
+::
+
+   oslopolicy-convert-json-to-yaml [-h] [--config-dir DIR] [--config-file PATH]
+                                   [--namespace NAMESPACE]
+                                   [--policy-file POLICY_FILE]
+                                   [--output-file OUTPUT_FILE]
+
+
+Description
+-----------
+
+The ``oslopolicy-convert-json-to-yaml`` tool can be used to convert the JSON
+format policy file to YAML format. It takes JSON formatted policy file as input
+and convert it to a YAML formatted policy file similar to
+``oslopolicy-sample-generator`` tool except keeping the overridden rule
+as uncommented. It does the following:
+
+* Comment out any rules that match the default from policy-in-code.
+* Keep rules uncommented if rule is overridden.
+* Does not auto add the deprecated rules in the file unless it not already
+  present in the file.
+* Keep any extra rules or already exist deprecated rules uncommented
+  but at the end of the file with a warning text.
+
+When to use:
+~~~~~~~~~~~~
+
+Oslo policy still support the policy file in JSON format, but that lead to
+`multiple issues <https://specs.openstack.org/openstack/oslo-specs/specs/victoria/policy-json-to-yaml.html#problem-description>`_ .
+One of the key issue came up while nova switched to the new policy with new
+defaults and scope feature from keystone.
+Refer `this bug <https://bugs.launchpad.net/nova/+bug/1875418>`_ for details.
+
+In future release, oslo policy will remove the JSON formatted policy
+file support and to have a smooth migration to YAML formatted policy file
+you can use this tool to convert your existing JSON formatted file to YAML
+file.
+
+Options
+-------
+
+.. include:: common/default-opts.rst
+
+.. include:: common/generator-opts.rst
+
+.. include:: common/convert-opts.rst
+
+Examples
+--------
+
+To convert a JSON policy file for a namespace called ``keystone``:
+
+.. code-block:: bash
+
+   oslopolicy-convert-json-to-yaml --namespace keystone \
+     --policy-file keystone-policy.json
+
+To convert a JSON policy file to yaml format directly to a file:
+
+.. code-block:: bash
+
+   oslopolicy-convert-json-to-yaml --namespace keystone \
+     --policy-file keystone-policy.json \
+     --output-file keystone-policy.yaml
+
+Use the following to generate help text for additional options and arguments
+supported by ``oslopolicy-convert-json-to-yaml``:
+
+.. code-block:: bash
+
+   oslopolicy-convert-json-to-yaml --help
+
+See Also
+--------
+
+:program:`oslopolicy-sample-generator`, :program:`oslopolicy-policy-generator`, :program:`oslopolicy-upgrade`