Clean up release notes before a release

Change-Id: I9aadc39ca27bf7e9eb23dd18217c86cf426f714b

releasenotes/notes/allow-periodics-shutdown-inspector-ac28ea5ba3224279.yaml

@@ -1,4 +1,5 @@
 ---
 other:
   - |
-    Allow a periodic task to shut down **ironic-inspector** upon a failure
+    Allows a periodic task to shut down an **ironic-inspector** process
+    upon a failure.

releasenotes/notes/firewall-refactoring-17e8ad764f2cde8d.yaml

@@ -1,12 +1,13 @@
 ---
 features:
   - |
-    The PXE filter drivers mechanism was enabled and the firewall-based
+    The PXE filter drivers mechanism is now enabled. The firewall-based
-    filtering was re-implemented in the ``iptables`` driver.
+    filtering was re-implemented as the ``iptables`` PXE filter driver.
 deprecations:
   - |
     The firewall-specific configuration options were moved from the
-    ``firewall`` to the ``iptables``. group.
+    ``firewall`` to the ``iptables`` group. All options in the ``iptables``
+    group are now deprecated.
   - |
     The generic firewall options ``firewall_update_period`` and
     ``manage_firewall`` were moved under the ``pxe_filter`` group as
@@ -15,9 +16,5 @@ fixes:
   - |
     Should the ``iptables`` PXE filter encounter an unexpected exception in the
     periodic ``sync`` call, the exception will be logged and the filter driver
-    will be reset in order to make subsequent ``sync`` calls fail (and propagate
+    will be reset in order to make subsequent ``sync`` calls fail (and
-    the failure exiting **inspector** eventually)
+    propagate the failure, exiting the **ironc-inspector** process eventually).
-other:
-  - |
-    The periodic sync of ``iptables`` and **ironic** is now handled by the
-    ``iptables`` PXE filter driver.

releasenotes/notes/policy-engine-c44828e3131e6c62.yaml

@@ -1,35 +1,38 @@
 ---
 features:
   - |
-    Added an API access policy enforcment (based on oslo.policy rules).
+    Adds an API access policy enforcment based on **oslo.policy** rules.
     Similar to other OpenStack services, operators now can configure
-    fine-grained access policies using ``policy.yaml`` file.
+    fine-grained access policies using ``policy.yaml`` file. See
-    See example ``policy.yaml.sample`` file included in the code tree
+    `policy.yaml.sample`_ in the code tree for the list of available policies
-    for the list of available policies and their default rules.
+    and their default rules. This file can also be generated from the code tree
-    This file can also be generated from the code tree
+    with the following command::
-    with ``tox -egenpolicy`` command.
 
-    See ``oslo.policy`` package documentation for more information
+        tox -egenpolicy
+
+    See the `oslo.policy package documentation`_ for more information
     on using and configuring API access policies.
 
+    .. _policy.yaml.sample: https://git.openstack.org/cgit/openstack/ironic-inspector/plain/policy.yaml.sample
+    .. _oslo.policy package documentation: https://docs.openstack.org/oslo.policy/latest/
 upgrade:
   - |
     Due to the choice of default values for API access policies rules,
-    some API parts of the ironic-inspector service will become available
+    some API parts of the **ironic-inspector** service will become available
     to wider range of users after upgrade:
 
-      - general access to the whole API is by default granted to a user
+    - general access to the whole API is by default granted to a user
-        with either ``admin``, ``administrator`` or ``baremetal_admin``
+      with either ``admin``, ``administrator`` or ``baremetal_admin`` role
-        role (previously it allowed access only to a user with ``admin``
+      (previously it allowed access only to a user with ``admin`` role)
-        role)
+    - listing of current introspection statuses and showing a given
-      - listing of current introspections and showing a given
+      introspection is by default also allowed to a user with the
-        introspection is by default also allowed to the user with the
+      ``baremetal_observer`` role
-        ``baremetal_observer`` role
 
-    If these access policies are not suiting a given deployment before
+    If these access policies are not appropriate for your deployment, override
-    upgrade, operator will have to create a ``policy.json`` file
+    them in a ``policy.json`` file in the **ironic-inspector** configuration
-    in the inspector configuration folder (usually ``/etc/inspector``)
+    directory (usually ``/etc/ironic-inspector``).
-    that redefines the API rules as required.
 
-    See ``oslo.policy`` package documentation for more information
+    See the `oslo.policy package documentation`_ for more information
     on using and configuring API access policies.
+
+    .. _oslo.policy package documentation: https://docs.openstack.org/oslo.policy/latest/