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
|
========
Usage
========
Creating New Release Notes
==========================
The ``reno`` command line tool is used to create a new release note
file in the correct format and with a unique name. 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.
::
$ reno new slug-goes-here
Created new notes file in releasenotes/notes/slug-goes-here-95915aaedd3c48d8.yaml
Within OpenStack projects, ``reno`` is often run via tox instead of
being installed globally. For example
::
$ tox -e venv -- reno new slug-goes-here
venv develop-inst-nodeps: /mnt/projects/release-notes-generation/reno
venv runtests: commands[0] | reno new slug-goes-here
Created new notes file in releasenotes/notes/slug-goes-here-95915aaedd3c48d8.yaml
venv: commands succeeded
congratulations :)
$ git status
Untracked files:
(use "git add <file>..." to include in what will be committed)
releasenotes/notes/slug-goes-here-95915aaedd3c48d8.yaml
By default the new note is created under ``./releasenotes/notes``. Use
the ``--rel-notes-dir`` to change the parent directory (the ``notes``
subdirectory is always appended).
Editing a Release Note
======================
The note file is a YAML file with several sections. All of the text is
interpreted as having reStructuredText formatting.
prelude
General comments about the release. The prelude from all notes in a
section are combined, in note order, to produce a single prelude
introducing that release.
features
A list of new major features in the release.
issues
A list of known issues in the release. For example, if a new driver
is experimental or known to not work in some cases, it should be
mentioned here.
upgrade
A list of upgrade notes in the release. For example, if a database
schema alteration is needed.
critical
A list of *fixed* critical bugs.
security
A list of *fixed* security issues.
fixes
A list of other *fixed* bugs.
other
Other notes that are important but do not fall into any of the given
categories.
Any sections that would be blank should be left out of the note file
entirely.
::
---
prelude: >
Replace this text with content to appear at the
top of the section for this release.
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.
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.
Formatting
----------
Release notes may include embedded reStructuredText, including simple
inline markup like emphasis and pre-formatted text as well as complex
body structures such as nested lists and tables. To use these
formatting features, the note must be escaped from the YAML parser.
The default template sets up the ``prelude`` section to use ``>`` so
that line breaks in the text are removed. This escaping mechanism is
not needed for the bullet items in the other sections of the template.
To escape the text of any section and *retain* the newlines, prefix
the value with ``|``. For example:
.. include:: ../../examples/notes/add-complex-example-6b5927c246456896.yaml
:literal:
See :doc:`examples` for the rendered version of the note.
Generating a Report
===================
Run ``reno report <path-to-git-repository>`` to generate a report
containing the release notes. The ``--branch`` argument can be used to
generate a report for a specific branch (the default is the branch
that is checked out). To limit the report to a subset of the available
versions on the branch, use the ``--version`` option (it can be
repeated).
Notes are output in the order they are found by ``git log`` looking
over the history of the branch. This is deterministic, but not
necessarily predictable or mutable.
|
