Update "Release Notes" in contributor docs

Moves the Release Notes section to its own page to give it a higher
level heading to make it easier to find.  Also updates info about
the Glance team's policy about the "prelude" section.

Change-Id: I31351068124e0981519ccc2e33a7bdc16f8197fd
This commit is contained in:
Brian Rosmaita 2018-08-09 17:38:56 -04:00
parent 3e187ac364
commit de6c36abaf
3 changed files with 61 additions and 39 deletions

View File

@ -99,42 +99,3 @@ which you may want to contribute:
file a bug. And, of course, we would also welcome your patch implementing file a bug. And, of course, we would also welcome your patch implementing
the improvement! the improvement!
Release Notes
-------------
Release notes are notes available for operators to get an idea what each
project has included and changed during a cycle. They may also include
various warnings and notices.
Generating release notes is done with Reno.
.. code-block:: bash
$ tox -e venv -- reno new <bug-,bp-,whatever>
This will generate a yaml file in ``releasenotes/notes`` that will contain
instructions about how to fill in (or remove) the various sections of
the document. Modify the yaml file as appropriate and include it as
part of your commit.
Commit your note to git (required for reno to pick it up):
.. code-block:: bash
$ git add releasenotes/notes/<note>; git commit
Once the release notes have been committed you can build them by using:
.. code-block:: bash
$ tox -e releasenotes
This will create the HTML files under ``releasenotes/build/html/``.
**NOTE**: The ``prelude`` section in the release notes is to highlight only the
important changes of the release. Please word your note accordingly and be
judicious when adding content there. We don't encourage extraneous notes and at
the same time we don't want to miss out on important ones. In short, not every
release note will need content in the ``prelude`` section. If what you're
working on required a spec, then a prelude is appropriate. If you're submitting
a bugfix, most likely not; a spec-lite is a judgement call.

View File

@ -25,6 +25,7 @@ Development Practices
:maxdepth: 3 :maxdepth: 3
blueprints blueprints
release-notes
documentation documentation
database_migrations database_migrations
.. bugs .. bugs

View File

@ -0,0 +1,60 @@
Release Notes
=============
Release notes are notes available for operators to get an idea what each
project has included and changed during a cycle. They may also include
various warnings and notices.
Generating release notes is done with Reno. You can submit a release note as a
yaml file with your patch, and Reno will gather and organize all the individual
notes into releases by looking at the commit hash associated with the yaml file
to see where it falls relative to branches/tags, and generate a single page of
notes for each release.
OpenStack has adopted Reno because it allows release notes to be written at the
time the code is committed. At that time, the impact of the change is still
clear in everyone's mind, and it avoids the situation where the PTL is
scrambling to write a detailed set of notes at the last minute.
You can read through the past `Glance Release Notes
<https://docs.openstack.org/releasenotes/glance/index.html>`_
to get a sense of what changes require a release note. If you're not sure,
ask in IRC or at the weekly Glance meeting. Sometimes a reviewer will force
the issue by adding "needs a release note" as a comment on your gerrit review.
A lot of people who write high-quality code are not comfortable writing release
notes. If you are such a person, and you're working on a patch that requires
a release note, you can ask in IRC or at the weekly Glance meeting for a
volunteer to take care of the release note for you.
You use Reno to generate a release note as follows:
.. code-block:: bash
$ tox -e venv -- reno new <bug-,bp-,whatever>
This will generate a yaml file in ``releasenotes/notes`` that will contain
instructions about how to fill in (or remove) the various sections of
the document. Modify the yaml file as appropriate and include it as
part of your commit.
.. note::
The Glance team has adopted the convention that the PTL writes the
``prelude`` section for a cycle's release notes at release time, when
it's clear what's been accomplished during the cycle and what should be
highlighted. So don't include a ``prelude`` section in your release
note.
Commit your note to git (required for reno to pick it up):
.. code-block:: bash
$ git add releasenotes/notes/<note>; git commit
Once the release notes have been committed you can build them by using:
.. code-block:: bash
$ tox -e releasenotes
This will create the HTML files under ``releasenotes/build/html/``.