Merge "[policy in code] part 7 add sample and releasenote"

.gitignore

@@ -26,7 +26,10 @@ etc/heat/heat.conf.sample
 heat_integrationtests/requirements.txt
 
 # generated policy file
-etc/heat/policy.json.sample
+etc/heat/policy.yaml.sample
+
+# sample policy file included in docs
+doc/source/_static/heat.policy.yaml.sample
 
 # Files created by releasenotes build
 releasenotes/build

doc/source/conf.py

@@ -78,10 +78,16 @@ extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.viewcode',
               'sphinx.ext.doctest',
               'openstackdocstheme',
+              'oslo_policy.sphinxext',
+              'oslo_policy.sphinxpolicygen',
               'ext.resources',
               'ext.tablefromtext',
               'stevedore.sphinxext']
 
+# policy sample file generation
+policy_generator_config_file = '../../etc/heat/heat-policy-generator.conf'
+sample_policy_basename = '_static/heat'
+
 # openstackdocstheme options
 repository_name = 'openstack/heat'
 bug_project = 'heat'
@@ -180,7 +186,7 @@ html_theme_options = {"sidebar_mode": "toc"}
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
+html_static_path = ['_static']
 
 # Add any paths that contain "extra" files, such as .htaccess or
 # robots.txt.

doc/source/configuration/index.rst

@@ -9,3 +9,4 @@ Configuring Heat
    clients.rst
    config-options.rst
    logs.rst
+   sample_policy.rst

doc/source/configuration/sample_policy.rst

@@ -0,0 +1,18 @@
+==================
+Heat Sample Policy
+==================
+
+The following is a sample heat policy file that has been auto-generated
+from default policy values in code. If you're using the default policies, then
+the maintenance of this file is not necessary, and it should not be copied into
+a deployment. Doing so will result in duplicate policy definitions. It is here
+to help explain which policy operations protect specific heat APIs, but it
+is not suggested to copy and paste into a deployment unless you're planning on
+providing a different policy for an operation that is not the default.
+
+If you wish build a policy file, you can also use ``tox -e genpolicy`` to
+generate it.
+
+The sample policy file can also be downloaded in `file form <../_static/heat.policy.yaml.sample>`_.
+
+.. literalinclude:: ../_static/heat.policy.yaml.sample

doc/source/index.rst

@@ -113,7 +113,6 @@ API Documentation
 
    .. _`Heat REST API Reference (OpenStack API Complete Reference - Orchestration)`: http://developer.openstack.org/api-ref/orchestration/v1/
 
-
 Code Documentation
 ==================
 .. toctree::

etc/heat/heat-policy-generator.conf

@@ -1,4 +1,3 @@
 [DEFAULT]
-format = json
 namespace = heat
-output_file = etc/heat/policy.json.sample
+output_file = etc/heat/policy.yaml.sample

releasenotes/notes/policy-in-code-124372f6cdb0a497.yaml

@@ -0,0 +1,15 @@
+---
+features:
+  - |
+    Heat now support policy in code, which means if you didn't modify any of
+    policy rules, you won't need to add rules in the `policy.yaml` or
+    `policy.json` file. Because from now, heat keeps all default policies under
+    `heat/policies`. You can still generate and modify a `policy.yaml` file
+    which will override policy rules in code if those rules appear in the
+    `policy.yaml` file.
+upgrade:
+  - |
+    Default policy.json file is now removed as we now generate the default
+    policies in code. Please be aware that when using that file in your
+    environment. You still can generate a `policy.yaml` file if that's required
+    in your environment.