Multiple tweaks for Ocata release notes

Those hopefully are of benefit. The major bit of the change is stopping
to use prelude section for all current release notes. This is because
the section is supposed to contain global release notes, not
feature-specific.

Other tweaks are open for debate.

Change-Id: I1d5e46591195a9756ee9fd5276f163794c366528

releasenotes/notes/Adds-http_proxy_to_wsgi-middleware-24e8271cbd94ffdf.yaml

@@ -1,11 +1,11 @@
 ---
 features:
-  - Middleware was added to parse the X-Forwarded-Proto HTTP header or the
+  - Middleware was added to parse the ``X-Forwarded-Proto`` HTTP header or the
-    Proxy protocol in order to help neutron respond with the correct URL refs
+    Proxy protocol in order to help Neutron respond with the correct URL
-    when it's put behind a TLS proxy (such as HAProxy). This adds
+    references when it's put behind a TLS proxy such as ``haproxy``. This adds
-    http_proxy_to_wsgi middleware to the pipeline. This middleware is disabled
+    ``http_proxy_to_wsgi`` middleware to the pipeline. This middleware is
-    by default, but can be enabled via a configuration option in the
+    disabled by default, but can be enabled via a configuration option in the
-    oslo_middleware group.
+    ``[oslo_middleware]`` group.
 upgrade:
-  - The api-paste.ini configuration file for the paste pipeline was updated to
+  - The ``api-paste.ini`` configuration file for the paste pipeline was updated
-    add the http_proxy_to_wsgi middleware.
+    to add the ``http_proxy_to_wsgi`` middleware.

releasenotes/notes/Dscp-marking-for-linuxbridge-agent-e765d0d934fa4017.yaml

@@ -1,6 +1,3 @@
 ---
-prelude: >
-    The LinuxBridge agent now supports QoS DSCP marking.
 features:
-  - The LinuxBridge agent can now configure DSCP marking for packets outgoing
+  - The Linux Bridge agent now supports QoS DSCP marking rules.
-    for ports with QoS policy.

releasenotes/notes/add-keepalived-vrrp-healt-check-f23ed7c853151484.yaml

@@ -1,11 +1,9 @@
 ---
-prelude: >
-    Keepalived VRRP health check functionality to enable verification of
-    connectivity from the "master" router to all gateways.
 features:
-  - Activation of this feature enables gateway connectivity validation and
+  - Keepalived VRRP health check functionality to enable verification of
-    rescheduling of the "master" router to another node when connectivity
+    connectivity from the "master" router to all gateways. Activation of this
-    is lost. If all routers lose connectivity to the gateways, the election
+    feature enables gateway connectivity validation and rescheduling of the
-    process will be repeated round-robin until one of the routers restores
+    "master" router to another node when connectivity is lost. If all routers
-    its gateway connection. In the mean time, all of the routers will be
+    lose connectivity to the gateways, the election process will be repeated
-    reported as "master".
+    round-robin until one of the routers restores its gateway connection. In
+    the mean time, all of the routers will be reported as "master".

releasenotes/notes/add-minimum-bandwidth-support-linuxbridge-9dc9d4458d8affef.yaml

@@ -1,6 +1,6 @@
 ---
 features:
-  - Linux Bridge now supports egress minimum bandwidth configuration.
+  - Linux Bridge driver now supports QoS egress minimum bandwidth limit rules.
 deprecations:
-  - Configuration parameters ``kernel_hz`` and ``tbf_latency`` in ``QoS``
+  - Configuration options ``kernel_hz`` and ``tbf_latency`` in ``[qos]``
-    section have been removed, because tc-tbf is no longer used.
+    section have been removed due to being no longer used.

releasenotes/notes/add-placement-api-configuration-options-f1611d0909bf6166.yaml

@@ -1,14 +1,11 @@
 ---
-prelude: >
-    Add configuration options to enable the segments plugin to use the
-    placement ReST API. This API enables the segments plugin to influence
-    the placement of instances based on the availability of IPv4 addresses
-    in routed networks.
 features:
-  - A new section is added to neutron.conf, `[placement]`.
+  - Add a new configuration section, ``[placement]``, with two new options that
-  - The `[placement]` section has two new options.
+    allow to make ``segments`` plugin to use the ``Compute`` placement ReST
-  - First option, `region_name`, indicates the placement region to use. This
+    API. This API allows to influence node placement of instances based on
-    option is useful if keystone manages more than one region.
+    availability of IPv4 addresses in routed networks. The first option,
-  - Second option, `endpoint_type`, indicates the type of the placement
+    `region_name`, indicates the placement region to use. This option is useful
-    endpoint to use. This endpoint will be looked up in the keystone catalog
+    if keystone manages more than one region. The second option,
-    and should be one of 'public', 'internal' or 'admin'.
+    `endpoint_type`, determines the type of a placement endpoint to use. This
+    endpoint will be looked up in the keystone catalog and should be one of
+    ``public``, ``internal`` or ``admin``.

releasenotes/notes/deprecate-SRIOV-physical_device_mappings-67dd3317181eb513.yaml

@@ -1,7 +1,6 @@
 ---
 deprecations:
-  - The 'physical_device_mappings' option is deprecated
+  - The ``physical_device_mappings`` option is deprecated and will be removed
-    and will be removed in Pike. The PCI device validation
+    in Pike. PCI device validation is done in Nova, controlled via the
-    is made in Nova with the 'pci_whitelist' config option.
+    ``pci_whitelist`` configuration option.  Therefore it is redundant to
-    Therefore it is redundant to validate it in Neutron
+    validate it in Neutron with ``physical_device_mappings``.
-    with physical_device_mappings.

releasenotes/notes/deprecate-send_arp_for_ha-0281853632f58e8d.yaml

@@ -1,5 +1,5 @@
 ---
 deprecations:
-  - L3 agent send_arp_for_ha configuration option is deprecated and will be
+  - The L3 agent ``send_arp_for_ha configuration`` option is deprecated and
-    removed in Pike. The functionality will remain and the agent will send
+    will be removed in Pike. The functionality will remain, and the agent will
-    three gratuitious ARPs whenever a new floating IP is configured.
+    send three gratuitious ARPs whenever a new floating IP is configured.

releasenotes/notes/designate-driver-keystonev3-8e70d152e84388e0.yaml

@@ -1,9 +1,7 @@
 ---
-prelude: >
-    Designate driver can use Keystone v3 auth options.
 features:
-  - "[designate] section accepts now auth_type parameter,
+  - Designate driver can now use Keystone v3 authentication options.  "The
-    and the usual keystoneauth options (e.g. auth_url,
+    ``[designate]`` section now accepts the ``auth_type`` option, as well as
-    username, user_domain_name, password, project_name,
+    other ``keystoneauth`` options (e.g. ``auth_url``, ``username``,
-    project_domain_name), so Keystone v3 endpoints can
+    ``user_domain_name``, ``password``, ``project_name``,
-    be used."
+    ``project_domain_name``)."

releasenotes/notes/dhcp-domain-removed-cc5bc6e2129fdf7f.yaml

@@ -1,5 +1,4 @@
 upgrade:
-  - The configuration option dhcp_domain in the
+  - The ``dhcp_domain`` DHCP agent configuration option was deprecated in
-    dhcp_agent.ini file was deprecated in the Liberty
+    Liberty cycle, and now is no longer used. The ``dns_domain`` option should
-    cycle. This value is no longer supported, dns_domain
+    be used instead.
-    in neutron.conf should be used instead.

releasenotes/notes/dhcp-for-service-subnets-06f03d902f2fb738.yaml

@@ -1,10 +0,0 @@
----
-fixes:
-  - A special case has been added to allow the creation of DHCP ports
-    on Service Subnets that do not have the service type "network:dhcp",
-    provided that the subnet has 'enable_dhcp' set to 'True'.
-    This fixes the recurring error seen when neutron attempts to
-    automatically create a DHCP port on a dhcp-enabled subnet after the
-    subnet is created. See bug report
-    `1636963 <https://bugs.launchpad.net/neutron/+bug/1636963>`_ for
-    more details.

releasenotes/notes/dhcp-ipv6-address-update-ff18d1eb0c196bce.yaml

@@ -1,19 +1,12 @@
 ---
-prelude: >
-    IPv6 addresses in DHCP namespaces will now be
-    (correctly) statically configured by the DHCP agent.
 fixes:
-  - There is a race condition when adding ports in
+  - There is a race condition when adding ports in DHCP namespaces where an
-    DHCP namespaces where an IPv6 address could be
+    IPv6 address could be dynamically created via SLAAC from a Router
-    dynamically created via SLAAC from a Router
+    Advertisement sent from the L3 agent, leading to a failure to start the
-    Advertisement sent from the L3 agent, leading to
+    DHCP agent. This bug has been fixed, but care must be taken on an upgrade
-    a failure to start the DHCP agent. This bug has
+    dealing with any potentially stale dynamic addresses.  For more
-    been fixed, but care must be taken on an upgrade
+    information, see bug `1627902 <https://launchpad.net/bugs/1627902>`_.
-    dealing with any possibly stale dynamic addresses.
-    For more information, see bug
-    `1627902 <https://launchpad.net/bugs/1627902>`_.
 upgrade:
-  - On upgrade, IPv6 addresses in the DHCP namespaces
+  - On upgrade, IPv6 addresses in DHCP namespaces that have been created
-    that have been created dynmically via SLAAC will be
+    dynamically via SLAAC will be removed, and static IPv6 addresses will be
-    removed, and a static IPv6 address will be added
+    added instead.
-    instead.

releasenotes/notes/fip-janitor-53f0d42a7471c5ed.yaml

@@ -1,20 +1,8 @@
 ---
-prelude: >
-    Due to changes in internal L3 logic, a server
-    crash/backend failure during FIP creation may
-    leave dangling ports attached on external
-    networks. These ports can be identified by a
-    'PENDING' device_id. The neutron server will
-    attempt a cleanup periodically to address the issue.
 other:
-  - If a floating IP creation gets interrupted by
+  - Due to changes in internal L3 logic, a server crash/backend failure during
-    a server crash or backend failure, a port can
+    FIP creation may leave dangling ports attached on external networks. These
-    be left behind on the external network. Neutron
+    ports can be identified by a ``PENDING`` ``device_id`` parameter. While
-    will now automatically clean these up after
+    those ports can also be removed by admins, the ``neutron-server`` service
-    approximately 10 minutes. This time value is not
+    will now also trigger periodic (approximately once in 10 minutes) cleanup
-    configurable.
+    to address the issue.
-  - Ports in this state will be visible on the external
-    network to admins, and will have a device_id value
-    of 'PENDING'. They can also be removed manually by
-    an admin if waiting for the periodic job to do it is
-    undesired.

releasenotes/notes/iptables-fail-on-missing-sysctl-bridge-firewalling-912f157b5671363f.yaml

@@ -1,7 +1,7 @@
 ---
 deprecations:
-    - The iptables firewall driver will no longer enable bridge firewalling in
+    - The ``iptables`` firewall driver will no longer enable bridge firewalling
-      next versions of Neutron. If your distribution overrides the default
+      in next versions of Neutron. If your distribution overrides the default
       value for any of relevant sysctl settings
       (``net.bridge.bridge-nf-call-arptables``,
       ``net.bridge.bridge-nf-call-ip6tables``, and
@@ -11,4 +11,4 @@ deprecations:
 upgrades:
     - On newer Linux kernels (3.18+) you will need to load the ``br_netfilter``
       kernel module before starting an Open vSwitch or Linuxbridge agent using
-      iptables based firewall. Otherwise the agent will fail to start.
+      ``iptables`` firewall driver. Otherwise the agent will fail to start.

releasenotes/notes/netns_cleanup_kill_procs-af88d8c47c07dd9c.yaml

@@ -1,8 +1,8 @@
 ---
 features:
-  - A new mechanism has been added to netns_cleanup to
+  - A new mechanism has been added to the ``neutron-netns-cleanup`` tool that
-    kill processes that are listening on any port/unix
+    allows to kill processes listening on any ``Unix`` or network socket within
-    socket within the namespace. This will try to kill
+    a namespace. The new mechanism will try to kill those processes gracefully
-    them gracefully via SIGTERM and, if they don't die,
+    using the ``SIGTERM`` signal and, if they refuse to die, then the
-    then a SIGKILL will be sent to the remaining
+    ``SIGKILL`` signal will be sent to each remaining process to ensure a
-    processes to ensure a proper cleanup.
+    proper cleanup.

releasenotes/notes/oslo.messaging.notify.drivers-abb0d17b9e1bd470.yaml

@@ -1,9 +1,11 @@
 ---
-prelude: |
+upgrade:
-  ``oslo.messaging.notify.drivers`` entry points have been removed
+  - Obsolete ``oslo.messaging.notify.drivers`` entrypoints that were left
-other:
+    in tree for backwards compatibility with pre-Icehouse releases have been
-  - |
+    removed. Those are ``neutron.openstack.common.notifier.log_notifier``,
-    The ``oslo.messaging.notify.drivers`` entry points that were left in
+    ``neutron.openstack.common.notifier.no_op_notifier``,
-    tree for backward compatibility with Icehouse have been removed.
+    ``neutron.openstack.common.notifier.test_notifier``,
-    Configure notifications using the oslo_messaging configuration options
+    ``neutron.openstack.common.notifier.rpc_notifier2``,
-    in ``neutron.conf``.
+    ``neutron.openstack.common.notifier.rpc_notifier``.
+    Use values provided by ``oslo.messaging`` library to configure notification
+    drivers.

releasenotes/notes/remove-min-l3-agents-per-router-27aef7d91dec0348.yaml

@@ -1,12 +1,12 @@
 ---
 upgrade:
-  - The neutron.conf:min_l3_agents_per_router option was
+  - The ``min_l3_agents_per_router`` configuration option was
-    deprecated in Newton and removed in Ocata. HA routers
+    deprecated in Newton cycle and removed in Ocata. HA routers
     no longer require a minimal number of L3 agents to
-    be created, although obviously require at least
+    be created, although obviously they require at least
-    two L3 agents to provide HA. The rationale for the
+    two L3 agents to provide HA guarantees. The rationale for the
     removal of the option is the case a router was created
     just when an agent was not operational. The creation
-    of the router will now succeed and when a second agent
+    of the router will now succeed, and when a second agent
     resumes operation the router will be scheduled to it
     providing HA.

releasenotes/notes/sending-garp-for-l3-ha-c118871833ad8743.yaml

@@ -1,18 +1,17 @@
 ---
 issues:
-  - In kernels < 3.19 net.ipv4.ip_nonlocal_bind was not
+  - In kernels < 3.19 ``net.ipv4.ip_nonlocal_bind`` sysctl option was not
-    a per-namespace kernel option. L3 HA sets this option
+    isolated to network namespace scope. L3 HA sets this option to zero to
-    to zero to avoid sending gratuitous ARPs for IP addresses
+    avoid sending gratuitous ARPs for IP addresses that were removed while
-    that were removed while processing. If this happens then
+    processing. If this happens, then gratuitous ARPs will be sent.  It may
-    gratuitous ARPs are going to be sent which might populate
+    populate ARP cache tables of peer machines with wrong MAC addresses.
-    ARP caches of peer machines with the wrong MAC address.
 fixes:
-  - Versions of keepalived < 1.2.20 don't send gratuitous ARPs
+  - Versions of ``keepalived`` < 1.2.20 don't send gratuitous ARPs when
-    when keepalived process receives SIGHUP signal. These
+    keepalived process receives a ``SIGHUP`` signal. These versions are not
-    versions are not packaged in some Linux distributions like
+    packaged in some Linux distributions like Red Hat Enterprise Linux 7,
-    RHEL, CentOS or Ubuntu Xenial. Not sending gratuitous ARPs
+    CentOS 7, or Ubuntu Xenial. Not sending gratuitous ARPs may lead to peer
-    may lead to peer ARP caches containing wrong information
+    ARP cache tables containing wrong entries about floating IP addresses until
-    about floating IP addresses until the entry is invalidated.
+    those entries are invalidated.  To fix that scenario, Neutron now sends
-    Neutron now sends gratuitous ARPs for all new IP addresses
+    gratuitous ARPs for all new IP addresses that appear on non-HA interfaces
-    that appear on non-HA interfaces in router namespace which
+    in router namespaces. This behavior simulates behavior of new versions of
-    simulates behavior of new versions of keepalived.
+    ``keepalived``.

releasenotes/notes/timestamp_format_change-73eda78566b4690b.yaml

@@ -1,16 +1,12 @@
 ---
-prelude: >
+features:
-  - The created_at and updated_at fields available on Neutron
+  - The ``created_at`` and ``updated_at`` resource fields now include a
-    resources now include a timezone indicator at the end.
+    timezone indicator at the end.  Because this is a change in field format,
-    Because this is a change in format, the old 'timestamp_core'
+    the old ``timestamp_core`` extension has been removed and replaced with a
-    extension has been removed and replaced with a 'timestamp'
+    ``standard-attr-timestamp`` extension.
-    extension.
 upgrade:
-  - The 'timestamp_core' extension has been removed and replaced
+  - The ``timestamp_core`` extension has been removed and replaced with the
-    with the 'standard-attr-timestamp' extension. Objects will still
+    ``standard-attr-timestamp`` extension. Resources will still have timestamps
-    have timestamps in the 'created_at' and 'updated_at' fields, but
+    in the ``created_at`` and ``updated_at`` fields, but timestamps will have
-    they will have the timestamp appended to the end of them
+    time zone info appended to the end to be consistent with other OpenStack
-    to be consistent with other OpenStack projects.
+    projects.
-fixes:
-  - Bug 1561200 has been fixed by including the timezone with
-    Neutron 'created_at' and 'updated_at' fields.

releasenotes/notes/use-pyroute2-in-ip-lib-558bfea8f14d1fea.yaml

@@ -1,4 +1,4 @@
 ---
 features:
-  - Initial support for oslo.privsep has been added. A usage example,
+  - Initial support for ``oslo.privsep`` has been added. Most external commands
-    including unit tests, exists with ip_lib.get_routing_table.
+    are still executed using ``oslo.rootwrap``.

releasenotes/notes/vhost-user-reconnect-7650134520022e7d.yaml

@@ -1,21 +1,14 @@
 ---
 features:
-  - vhost-user reconnect is a mechanism  which allows
+  - vhost-user reconnect is a mechanism  which allows a vhost-user frontend to
-    a vhost-user frontend to reconnect to a vhost-user
+    reconnect to a vhost-user backend in the event the backend terminates
-    backend in the event the backend terminates.
+    either as a result of a graceful shutdown or a crash.  This allows a VM
-    This enable a VM utilising a vhost-user interface
+    utilising a vhost-user interface to reconnect automatically to the backend
-    to reconnect automatically to the backend e.g.
+    e.g.  Open vSwitch without requiring the VM to reboot.  In this release,
-    a vSwitch without requiring the VM to reboot.
+    support was added to the neutron Open vSwitch agent and ``ml2`` driver for
-    In this release, support was added to the neutron
+    vhost-user reconnect.
-    Open vSwitch agent and ml2 driver for vhost-user
-    reconnect.
 other:
-  - vhost-user reconnect allows VMs using vhost-user
+  - vhost-user reconnect requires dpdk 16.07 and qemu 2.7 and openvswitch 2.6
-    interfaces to reconnect to the vhost-user backend if
+    to function. if an older qemu is used, reconnect will not be available but
-    the backend terminates either as a result of a graceful
+    vhost-user will still function.
-    shutdown or a crash without requiring the VM to reboot.
-  - vhost-user reconnect requires dpdk 16.07 and qemu 2.7
-    and ovs 2.6 to function. if an older qemu is used,
-    reconnect will not be available but vhost-user will
-    still function.