Browse Source

Update "Release Notes" in contributor docs

Moves the Release Notes section to its own page to give it a higher
level heading to make it easier to find.  Also updates info about
the Glance team's policy about the "prelude" section.

Change-Id: I31351068124e0981519ccc2e33a7bdc16f8197fd
Brian Rosmaita 8 months ago
parent
commit
de6c36abaf

+ 0
- 39
doc/source/contributor/documentation.rst View File

@@ -99,42 +99,3 @@ which you may want to contribute:
99 99
   file a bug.  And, of course, we would also welcome your patch implementing
100 100
   the improvement!
101 101
 
102
-Release Notes
103
--------------
104
-
105
-Release notes are notes available for operators to get an idea what each
106
-project has included and changed during a cycle. They may also include
107
-various warnings and notices.
108
-
109
-Generating release notes is done with Reno.
110
-
111
-.. code-block:: bash
112
-
113
-    $ tox -e venv -- reno new <bug-,bp-,whatever>
114
-
115
-This will generate a yaml file in ``releasenotes/notes`` that will contain
116
-instructions about how to fill in (or remove) the various sections of
117
-the document. Modify the yaml file as appropriate and include it as
118
-part of your commit.
119
-
120
-Commit 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
-
126
-Once the release notes have been committed you can build them by using:
127
-
128
-.. code-block:: bash
129
-
130
-   $ tox -e releasenotes
131
-
132
-This will create the HTML files under ``releasenotes/build/html/``.
133
-
134
-**NOTE**: The ``prelude`` section in the release notes is to highlight only the
135
-important changes of the release. Please word your note accordingly and be
136
-judicious when adding content there. We don't encourage extraneous notes and at
137
-the same time we don't want to miss out on important ones. In short, not every
138
-release note will need content in the ``prelude`` section. If what you're
139
-working on required a spec, then a prelude is appropriate. If you're submitting
140
-a bugfix, most likely not; a spec-lite is a judgement call.

+ 1
- 0
doc/source/contributor/index.rst View File

@@ -25,6 +25,7 @@ Development Practices
25 25
    :maxdepth: 3
26 26
 
27 27
    blueprints
28
+   release-notes
28 29
    documentation
29 30
    database_migrations
30 31
 .. bugs

+ 60
- 0
doc/source/contributor/release-notes.rst View File

@@ -0,0 +1,60 @@
1
+Release Notes
2
+=============
3
+
4
+Release notes are notes available for operators to get an idea what each
5
+project has included and changed during a cycle. They may also include
6
+various warnings and notices.
7
+
8
+Generating release notes is done with Reno.  You can submit a release note as a
9
+yaml file with your patch, and Reno will gather and organize all the individual
10
+notes into releases by looking at the commit hash associated with the yaml file
11
+to see where it falls relative to branches/tags, and generate a single page of
12
+notes for each release.
13
+
14
+OpenStack has adopted Reno because it allows release notes to be written at the
15
+time the code is committed.  At that time, the impact of the change is still
16
+clear in everyone's mind, and it avoids the situation where the PTL is
17
+scrambling to write a detailed set of notes at the last minute.
18
+
19
+You can read through the past `Glance Release Notes
20
+<https://docs.openstack.org/releasenotes/glance/index.html>`_
21
+to get a sense of what changes require a release note.  If you're not sure,
22
+ask in IRC or at the weekly Glance meeting.  Sometimes a reviewer will force
23
+the issue by adding "needs a release note" as a comment on your gerrit review.
24
+
25
+A lot of people who write high-quality code are not comfortable writing release
26
+notes.  If you are such a person, and you're working on a patch that requires
27
+a release note, you can ask in IRC or at the weekly Glance meeting for a
28
+volunteer to take care of the release note for you.
29
+
30
+You 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
+
36
+This will generate a yaml file in ``releasenotes/notes`` that will contain
37
+instructions about how to fill in (or remove) the various sections of
38
+the document. Modify the yaml file as appropriate and include it as
39
+part 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
+
48
+Commit 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
+
54
+Once the release notes have been committed you can build them by using:
55
+
56
+.. code-block:: bash
57
+
58
+   $ tox -e releasenotes
59
+
60
+This will create the HTML files under ``releasenotes/build/html/``.

Loading…
Cancel
Save