glance/doc/source/contributor/release-notes.rst

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 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:

$ 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):

$ git add releasenotes/notes/<note>; git commit

Once the release notes have been committed you can build them by using:

$ tox -e releasenotes

This will create the HTML files under releasenotes/build/html/.