Release notes

The release notes for a patch should be included in the patch.

If the following applies to the patch, a release note is required:

  • Upgrades

    • The deployer needs to take an action when upgrading

    • A new config option is added that the deployer should consider changing from the default

    • A configuration option is deprecated or removed

  • Features

    • A new feature or driver is implemented

    • Feature is deprecated or removed

    • Current behavior is changed

  • Bugs

    • A security bug is fixed

    • A long-standing or important bug is fixed

  • APIs

    • REST API changes

Bugs

For bug fixes, release notes must include the bug number in Launchpad with a link to it as a RST link like in the following example:

---
fixes:
  - |
    `Bug #1889758 <https://bugs.launchpad.net/cinder/+bug/1889758>`_: Fixed
    revert to snapshot not working for non admin users when using the
    snapshot's name.

Note the use of the past tense (“Fixed”) instead of the present tense (“Fix”). This is because although you are fixing the bug right now in the present, operators will be reading the release notes in the future (at the time of the release), at which time your bug fix will be a thing of the past.

Additionally, keep in mind that when your release note is published, it is mixed in with all the other release notes and won’t obviously be connected to your patch. Thus, in order for it to make sense, you may need to repeat information that you already have in your commit message. That’s OK.

Drivers

For release notes related to a specific driver -be it volume, backup, or zone manager- the release note line must start with <driver-name> driver:. For example:

---
features:
  - |
    RBD driver: Added support for volume manage and unmanage operations.

When fixing a driver bug we must not only have the driver name prefix but also the bug number and link:

---
fixes:
  - |
    Brocade driver `bug #1866860
    <https://bugs.launchpad.net/cinder/+bug/1889758>`_: Fixed
    ``AttributeError`` when using ``REST_HTTP`` or ``REST_HTTPS`` as the
    ``fc_southbound_protocol`` option and an exception is raised by the
    client.

There are times when a bug affects multiple drivers. In such a cases we must list each of the driver as an independent item following above rules:

---
fixes:
  - |
    Unity driver `bug #1881108
    <https://bugs.launchpad.net/cinder/+bug/1881108>`_: Fixed leaving
    leftover devices on the host when validation of the attached volume
    fails on some cloning cases and create volume from snapshot.
  - |
    Kaminario driver `bug #1881108
    <https://bugs.launchpad.net/cinder/+bug/1881108>`_:  Fixed leaving
    leftover devices on the host when validation of the attached volume
    fails on some cloning cases and create volume from snapshot.

Creating the note

Cinder uses reno to generate release notes. Please read the docs for details. In summary, use

$ tox -e venv -- reno new <bug-,bp-,whatever>

Then edit the sample file that was created and push it with your change.

To see the results:

$ git commit  # Commit the change because reno scans git log.

$ tox -e releasenotes

Then look at the generated release notes files in releasenotes/build/html in your favorite browser.