summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorZuul <zuul@review.openstack.org>2018-08-15 13:38:06 +0000
committerGerrit Code Review <review@openstack.org>2018-08-15 13:38:06 +0000
commit0c41ab9ae21816bccc6da0fe561e1b1bfe8d1370 (patch)
treed5a491d638be5769d95eaa84936c0e5e8a071424
parent89d9d59a6ebfd2969103ccaee564f597f7aec14b (diff)
parentde6c36abafa1765027b33568e76307959d9a19ed (diff)
Merge "Update "Release Notes" in contributor docs"
-rw-r--r--doc/source/contributor/documentation.rst39
-rw-r--r--doc/source/contributor/index.rst1
-rw-r--r--doc/source/contributor/release-notes.rst60
3 files changed, 61 insertions, 39 deletions
diff --git a/doc/source/contributor/documentation.rst b/doc/source/contributor/documentation.rst
index 48731ef..6d9fd40 100644
--- a/doc/source/contributor/documentation.rst
+++ b/doc/source/contributor/documentation.rst
@@ -99,42 +99,3 @@ which you may want to contribute:
99 file a bug. And, of course, we would also welcome your patch implementing 99 file a bug. And, of course, we would also welcome your patch implementing
100 the improvement! 100 the improvement!
101 101
102Release Notes
103-------------
104
105Release notes are notes available for operators to get an idea what each
106project has included and changed during a cycle. They may also include
107various warnings and notices.
108
109Generating release notes is done with Reno.
110
111.. code-block:: bash
112
113 $ tox -e venv -- reno new <bug-,bp-,whatever>
114
115This will generate a yaml file in ``releasenotes/notes`` that will contain
116instructions about how to fill in (or remove) the various sections of
117the document. Modify the yaml file as appropriate and include it as
118part of your commit.
119
120Commit your note to git (required for reno to pick it up):
121
122.. code-block:: bash
123
124 $ git add releasenotes/notes/<note>; git commit
125
126Once the release notes have been committed you can build them by using:
127
128.. code-block:: bash
129
130 $ tox -e releasenotes
131
132This will create the HTML files under ``releasenotes/build/html/``.
133
134**NOTE**: The ``prelude`` section in the release notes is to highlight only the
135important changes of the release. Please word your note accordingly and be
136judicious when adding content there. We don't encourage extraneous notes and at
137the same time we don't want to miss out on important ones. In short, not every
138release note will need content in the ``prelude`` section. If what you're
139working on required a spec, then a prelude is appropriate. If you're submitting
140a bugfix, most likely not; a spec-lite is a judgement call.
diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
index d19af2e..12d2c8a 100644
--- a/doc/source/contributor/index.rst
+++ b/doc/source/contributor/index.rst
@@ -25,6 +25,7 @@ Development Practices
25 :maxdepth: 3 25 :maxdepth: 3
26 26
27 blueprints 27 blueprints
28 release-notes
28 documentation 29 documentation
29 database_migrations 30 database_migrations
30.. bugs 31.. bugs
diff --git a/doc/source/contributor/release-notes.rst b/doc/source/contributor/release-notes.rst
new file mode 100644
index 0000000..0d366ef
--- /dev/null
+++ b/doc/source/contributor/release-notes.rst
@@ -0,0 +1,60 @@
1Release Notes
2=============
3
4Release notes are notes available for operators to get an idea what each
5project has included and changed during a cycle. They may also include
6various warnings and notices.
7
8Generating release notes is done with Reno. You can submit a release note as a
9yaml file with your patch, and Reno will gather and organize all the individual
10notes into releases by looking at the commit hash associated with the yaml file
11to see where it falls relative to branches/tags, and generate a single page of
12notes for each release.
13
14OpenStack has adopted Reno because it allows release notes to be written at the
15time the code is committed. At that time, the impact of the change is still
16clear in everyone's mind, and it avoids the situation where the PTL is
17scrambling to write a detailed set of notes at the last minute.
18
19You can read through the past `Glance Release Notes
20<https://docs.openstack.org/releasenotes/glance/index.html>`_
21to get a sense of what changes require a release note. If you're not sure,
22ask in IRC or at the weekly Glance meeting. Sometimes a reviewer will force
23the issue by adding "needs a release note" as a comment on your gerrit review.
24
25A lot of people who write high-quality code are not comfortable writing release
26notes. If you are such a person, and you're working on a patch that requires
27a release note, you can ask in IRC or at the weekly Glance meeting for a
28volunteer to take care of the release note for you.
29
30You use Reno to generate a release note as follows:
31
32.. code-block:: bash
33
34 $ tox -e venv -- reno new <bug-,bp-,whatever>
35
36This will generate a yaml file in ``releasenotes/notes`` that will contain
37instructions about how to fill in (or remove) the various sections of
38the document. Modify the yaml file as appropriate and include it as
39part of your commit.
40
41.. note::
42 The Glance team has adopted the convention that the PTL writes the
43 ``prelude`` section for a cycle's release notes at release time, when
44 it's clear what's been accomplished during the cycle and what should be
45 highlighted. So don't include a ``prelude`` section in your release
46 note.
47
48Commit your note to git (required for reno to pick it up):
49
50.. code-block:: bash
51
52 $ git add releasenotes/notes/<note>; git commit
53
54Once the release notes have been committed you can build them by using:
55
56.. code-block:: bash
57
58 $ tox -e releasenotes
59
60This will create the HTML files under ``releasenotes/build/html/``.