From 75588809b53e22491acb298fdeeb810c945469fd Mon Sep 17 00:00:00 2001 From: Brian Rosmaita Date: Thu, 8 Apr 2021 14:31:08 -0400 Subject: Update release note info - add a link to make the release note info easier to find in the contributor guide to increase the likelihood that people will actually follow the standard format - add some guidance about using past tense to describe fixes - update the sample notes to reflect the above Change-Id: Iddf0b3de4ba44f9b14d2e144097b51fd7a4ccf61 --- doc/source/contributor/index.rst | 11 +++++++++++ doc/source/contributor/releasenotes.rst | 28 +++++++++++++++++++--------- reno.yaml | 6 +++--- 3 files changed, 33 insertions(+), 12 deletions(-) diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index a3066b727..456aae4e4 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -30,6 +30,17 @@ Getting Started contributing +Writing Release Notes +--------------------- + +Please follow the format, it will make everyone's life easier. There's +even a special section on writing release notes for Cinder drivers. + +.. toctree:: + :maxdepth: 2 + + releasenotes + .. _programming-howtos: Programming HowTos and Tutorials diff --git a/doc/source/contributor/releasenotes.rst b/doc/source/contributor/releasenotes.rst index de566b6a8..5f84a9291 100644 --- a/doc/source/contributor/releasenotes.rst +++ b/doc/source/contributor/releasenotes.rst @@ -56,10 +56,20 @@ link to it as a RST link like in the following example: --- fixes: - | - `Bug #1889758 `_: Fix + `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 ------- @@ -72,7 +82,7 @@ For example: --- features: - | - RBD driver: Add support for volume manage and unmanage operations. + 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: @@ -83,7 +93,7 @@ the bug number and link: fixes: - | Brocade driver `bug #1866860 - `_: Fix + `_: Fixed ``AttributeError`` when using ``REST_HTTP`` or ``REST_HTTPS`` as the ``fc_southbound_protocol`` option and an exception is raised by the client. @@ -97,14 +107,14 @@ list each of the driver as an independent item following above rules: fixes: - | Unity driver `bug #1881108 - `_: Fix leaving leftover - devices on the host when validation of the attached volume fails on some - cloning cases and create volume from snapshot. + `_: 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 - `_: Fix leaving leftover - devices on the host when validation of the attached volume fails on some - cloning cases and create volume from snapshot. + `_: 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 ----------------- diff --git a/reno.yaml b/reno.yaml index 55c9fa05e..4cd33255c 100644 --- a/reno.yaml +++ b/reno.yaml @@ -27,7 +27,7 @@ template: | a Cinder backup service can perform using the ``backup_max_operations`` configuration option. - | - RBD driver: Add support for volume manage and unmanage operations. + RBD driver: Added support for volume manage and unmanage operations. issues: - | List known issues here, or remove this section. All of the list items in @@ -71,12 +71,12 @@ template: | available in another section, such as the prelude. This may mean repeating some details. Examples for core code fixes, and driver fixes: - | - `Bug #1889758 `_: Fix + `Bug #1889758 `_: Fixed revert to snapshot not working for non admin users when using the snapshot's name. - | Brocade driver `bug #1866860 - `_: Fix + `_: Fixed ``AttributeError`` when using ``REST_HTTP`` or ``REST_HTTPS`` as the ``fc_southbound_protocol`` option and an exception is raised by the client. -- cgit v1.2.1