61 lines
2.4 KiB
ReStructuredText
61 lines
2.4 KiB
ReStructuredText
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/``.
|