openstack/deb-manila
Code Issues Proposed changes

Clarify language in release notes

Browse Source 
The end results aren't entirely pretty:
http://docs.openstack.org/releasenotes/manila/newton.html

Having these instructions may help developers and reviewers.

Change-Id: Ibfe6a0850cff72968d2917f0ceae0e70afa21625
This commit is contained in:
Goutham Pacha Ravi 2016-10-25 10:30:21 +02:00
parent 5faab23a36
commit 0b5125d285
1 changed files with 17 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
doc/source/devref/adding_release_notes.rst
View File

@ -22,12 +22,12 @@ What needs a release note?
deployer to take some action while upgrading deployer to take some action while upgrading
* API changes * API changes
* New APIs * New APIs
* Changes to the response schema of existing APIs * Changes to the response schema of existing APIs
* Changes to request/response headers * Changes to request/response headers
* Non-trivial API changes such as response code changes from 2xx to 4xx * Non-trivial API changes such as response code changes from 2xx to 4xx
* Deprecation of APIs or response fields * Deprecation of APIs or response fields
* Removal of APIs * Removal of APIs
* A new feature is implemented, such as a new core feature in manila, * A new feature is implemented, such as a new core feature in manila,
driver support for an existing manila feature or a new driver driver support for an existing manila feature or a new driver
@ -78,6 +78,11 @@ Or directly as a one-liner, with:
$ tox -e venv -- reno new slug-goes-here $ tox -e venv -- reno new slug-goes-here
.. note::
When you are adding a bug-fix reno, name your file using the template:
"bug-<launchpad-bug-id>-slug-goes-here".
Then add the notes in ``yaml`` format in the file created. Pay attention to the Then add the notes in ``yaml`` format in the file created. Pay attention to the
type of section. The following are general sections to use: type of section. The following are general sections to use:
@ -155,7 +160,7 @@ Dos and Don'ts
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
* Release notes need to be succinct. Short and unambiguous descriptions are * Release notes need to be succinct. Short and unambiguous descriptions are
preferred preferred
* Use present tense * Write in past tense, unless you are writing an imperative statement
* Do not have blank sections in the file * Do not have blank sections in the file
* Do not include code or links * Do not include code or links
* Avoid special rst formatting unless absolutely necessary * Avoid special rst formatting unless absolutely necessary
@ -166,6 +171,11 @@ Dos and Don'ts
* Limit a release note to fewer than 2-3 lines per change per section * Limit a release note to fewer than 2-3 lines per change per section
* OpenStack prefers atomic changes. So remember that your change may need the * OpenStack prefers atomic changes. So remember that your change may need the
fewest sections possible fewest sections possible
* General writing guidelines can be found
`here <http://docs.openstack
.org/contributor-guide/writing-style/general-writing-guidelines.html>`_
* Proofread your note. Pretend you are a user or a deployer who is reading
the note after a milestone or a release has been cut
Examples Examples
~~~~~~~~ ~~~~~~~~