1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
.. _adding_release_notes:
Release Notes
=============
What are release notes?
~~~~~~~~~~~~~~~~~~~~~~~
Release notes are important for change management within manila. Since manila
follows a release cycle with milestones, release notes provide a way for the
community and users to quickly grasp what changes occurred within a development
milestone. To the OpenStack release management and documentation teams,
release notes are a way to compile changes per milestone. These notes are
published on the `OpenStack Releases website <http://releases.openstack.org>`_.
Automated tooling is built around ``releasenotes`` and they get appropriately
handled per release milestone, including any back-ports to stable releases.
What needs a release note?
~~~~~~~~~~~~~~~~~~~~~~~~~~
* Changes that impact an upgrade, most importantly, those that require a
deployer to take some action while upgrading
* A new feature is implemented
* An existing feature is deprecated
* An existing feature is removed
* Behavior of an existing feature has changed in a discernible way to an end
user or administrator
* A security bug is fixed
* New configuration option is added
What does not need a release note?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* A code change that doesn't change the general behavior of any
feature such as code refactor or logging changes. One case of this could be
the removal of the python 2.x compatibility layer, i.e., the "six" library
from code.
* Functional or unit test coverage enhancement
* Any change submitted with a justified TrivialFix flag added in the commit
message
* Adding or changing documentation within in-tree documentation guides
How do I add a release note?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We use `Reno <https://docs.openstack.org/reno/latest/>`_ to create and manage
release notes. The new subcommand combines a random suffix with a "slug" value
to make the new file with a unique name that is easy to identify again later.
To create a release note for your change, use:
.. code-block:: console
$ reno new slug-goes-here
If reno is not installed globally on your system, you can use a tox
environment in manila:
.. code-block:: console
$ tox -e newnote -- 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
type of section. The following are general sections to use:
prelude
General comments about the change. The prelude from all notes in a
release are combined, in note order, to produce a single prelude
introducing the release.
features
New features introduced
issues
A list of known issues with respect to the change being introduced. For
example, if the new feature in the change is experimental or known to not
work in some cases, it should be mentioned here.
upgrade
A list of upgrade notes in the release. Any removals that affect upgrades are
to be noted here.
deprecations
Any features, APIs, configuration options that the change has deprecated.
Deprecations are not removals. Deprecations suggest that there will be
support for a certain timeline. Deprecation should allow time for users
to make necessary changes for the removal to happen in a future release.
It is important to note the timeline of deprecation in this section.
critical
A list of *fixed* critical bugs (descriptions only).
security
A list of *fixed* security issues (descriptions only).
fixes
A list of other *fixed* bugs (descriptions only).
other
Other notes that are important but do not fall into any of the given
categories.
::
---
prelude: >
Replace this text with content to appear at the
top of the section for this change.
features:
- List new features here, or remove this section.
issues:
- List known issues here, or remove this section.
upgrade:
- List upgrade notes here, or remove this section.
deprecations:
- List deprecation notes here, or remove this section
critical:
- Add critical notes here, or remove this section.
security:
- Add security notes here, or remove this section.
fixes:
- Add normal bug fixes here, or remove this section.
other:
- Add other notes here, or remove this section.
Dos and Don'ts
~~~~~~~~~~~~~~
* Release notes need to be succinct. Short and unambiguous descriptions are
preferred
* Write in past tense, unless you are writing an imperative statement
* Do not have blank sections in the file
* Do not include code or links
* Avoid special rst formatting unless absolutely necessary
* Always prefer including a release note in the same patch
* Release notes are not a replacement for developer/user/admin documentation
* Release notes are not a way of conveying behavior of any features or usage of
any APIs
* 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
fewest sections possible
* General writing guidelines can be found
`here <https://docs.openstack
.org/doc-contrib-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
|
