Clarify documentation for release notes

This was discussed in today's keystone meeting. It was decided that
there should be some more clarification around release notes and how
to update them.

Change-Id: I4a06fda76dc8589a755438ccc12bc0bf2f575dcb

doc/source/contributor/release-notes.rst

@@ -23,13 +23,32 @@ The Keystone team uses `reno
 notes. These are important user-facing documents that must be included when a
 user or operator facing change is performed, like a bug-fix or a new feature. A
 release note should be included in the same patch the work is being performed.
-Release notes should be easy to read and maintain; should link back to
-appropriate documentation readers may need. The following conventions help the
-team ensure all release notes achieve those goals.
+Release notes should be short, easy to read, and easy to maintain. They also
+`must` link back to any appropriate documentation if it exists. The following
+conventions help ensure all release notes achieve those goals.
 
 Most release notes either describe bug fixes or announce support for new
-features, both of which are tracked using Launchpad. When creating a release
-note that communicates a bug fix, use the bug number in the name of the note:
+features, both of which are tracked using Launchpad. The conventions below rely
+on links in Launchpad to provide readers with more context.
+
+.. warning::
+
+    We highly recommend taking careful thought when writing and reviewing
+    release notes. Once a release note has been published with a formal
+    release, updating it across releases will cause it to be published in a
+    subsequent release. Reviews that update, or modify, a release note from a
+    previous release outside of the branch it was added in should be rejected
+    unless it's required for a very specific case.
+
+    Please refer to reno's `documentation
+    <https://docs.openstack.org/reno/latest/user/usage.html>`_ for more
+    information.
+
+Release Notes for Bugs
+======================
+
+When creating a release note that communicates a bug fix, use the bug number in
+the name of the release note:
 
 .. code-block:: bash
 
@@ -39,11 +58,10 @@ note that communicates a bug fix, use the bug number in the name of the note:
 The body of the release note should clearly explain how the impact will affect
 users and operators. It should also include why the change was necessary but
 not be overspecific about implementation details, as that can be found in the
-commit. It should contain a properly formatted link in reStructuredText that
-points back to the original bug report used to track the fix. This makes
-reading release notes easier because readers can get a quick summary of the
-change, understand how it is going to impact them, and follow a link to more
-detail if they choose.
+commit and the bug report. It should contain a properly formatted link in
+reStructuredText that points back to the original bug report used to track the
+fix. This ensures the release note is kept short and to-the-point while
+providing readers with additional resources:
 
 .. code-block:: yaml
 
@@ -56,6 +74,10 @@ detail if they choose.
         be dangerous and the given reason for keeping it True was strictly for
         backwards compatability.
 
+
+Release Notes for Features
+==========================
+
 Release notes detailing feature work follow the same basic format, but instead
 of using the bug number in the name of the release note, use the blueprint slug
 used to track the feature work:
@@ -69,14 +91,14 @@ Just like release notes communicating bug fixes, release notes detailing
 feature work must contain a link back to the blueprint. Readers should be able
 to easily discover all patches that implement the feature, as well as find
 links to the full specification and documentation. All of this is typically
-found in the blueprint registered in Launchpad.
+found in the blueprint registered in Launchpad:
 
 .. code-block:: yaml
 
     ---
     features:
       - >
-        [`blueprint support-fizzbangs<https://blueprints.launchpad.net/keystone/+spec/support-fizzbangs>`_]
+        [`blueprint support-fizzbangs <https://blueprints.launchpad.net/keystone/+spec/support-fizzbangs>`_]
         Keystone now fully supports the usage of fizzbangs.
 
 In the rare case there is a release note that does not pertain to a bug or