Browse Source

Simplify Specs folder structure

Docs build on python3 has some extra demands, like that a global
toctree argument (e.g. ocata/*) always needs to list at least one
file. To satisfy that, the easiest solution was to remove the
"approved" and "implemented" folders. We were not using them anyhow.

Change-Id: I453e74932b95cc8f3e13e1fb74437f3da86f659f
Andreas Scheuring 1 year ago
parent
commit
7b4bbc20aa

+ 9
- 3
doc/source/index.rst View File

@@ -83,9 +83,15 @@ Contributing to the project
83 83
 
84 84
     contributing
85 85
     devref
86
-    specs/ocata/index
87
-    specs/pike/index
88
-    specs/queens/index
86
+
87
+Specs
88
+=====
89
+
90
+.. toctree::
91
+    :glob:
92
+    :maxdepth: 2
93
+
94
+    specs/index
89 95
 
90 96
 
91 97
 

+ 32
- 0
doc/source/specs/index.rst View File

@@ -0,0 +1,32 @@
1
+..
2
+      Copyright 2016 IBM
3
+      All Rights Reserved.
4
+
5
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
6
+      not use this file except in compliance with the License. You may obtain
7
+      a copy of the License at
8
+
9
+          http://www.apache.org/licenses/LICENSE-2.0
10
+
11
+      Unless required by applicable law or agreed to in writing, software
12
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14
+      License for the specific language governing permissions and limitations
15
+      under the License.
16
+
17
+Template
18
+========
19
+
20
+.. toctree::
21
+    :maxdepth: 1
22
+
23
+    template
24
+
25
+Ocata
26
+=====
27
+
28
+.. toctree::
29
+    :glob:
30
+    :maxdepth: 1
31
+
32
+    ocata/*

+ 0
- 0
doc/source/specs/ocata/approved/.dummy View File


+ 0
- 0
doc/source/specs/ocata/implemented/.dummy View File


+ 0
- 28
doc/source/specs/ocata/index.rst View File

@@ -1,28 +0,0 @@
1
-=================================
2
-Nova-dpm specifications for Ocata
3
-=================================
4
-
5
-**TODO:** Figure out what to do with this page and its child pages.
6
-
7
-Template:
8
-
9
-.. toctree::
10
-   :maxdepth: 1
11
-
12
-   Specification Template (Ocata release) <template>
13
-
14
-Specs implemented in Ocata:
15
-
16
-.. toctree::
17
-   :glob:
18
-   :maxdepth: 1
19
-
20
-   implemented/*
21
-
22
-Specs approved (but not implemented) in Ocata:
23
-
24
-.. toctree::
25
-   :glob:
26
-   :maxdepth: 1
27
-
28
-   approved/*

doc/source/specs/ocata/approved/neutron_integration_base.rst → doc/source/specs/ocata/neutron_integration_base.rst View File


doc/source/specs/ocata/approved/neutron_integration_set_mac.rst → doc/source/specs/ocata/neutron_integration_set_mac.rst View File


+ 0
- 0
doc/source/specs/pike/approved/.dummy View File


+ 0
- 0
doc/source/specs/pike/implemented/.dummy View File


+ 0
- 26
doc/source/specs/pike/index.rst View File

@@ -1,26 +0,0 @@
1
-================================
2
-Nova-dpm specifications for Pike
3
-================================
4
-
5
-Template:
6
-
7
-.. toctree::
8
-   :maxdepth: 1
9
-
10
-   Specification Template (Pike release) <template>
11
-
12
-Specs implemented in Pike:
13
-
14
-.. toctree::
15
-   :glob:
16
-   :maxdepth: 1
17
-
18
-   implemented/*
19
-
20
-Specs proposed / approved for Pike:
21
-
22
-.. toctree::
23
-   :glob:
24
-   :maxdepth: 1
25
-
26
-   approved/*

+ 0
- 397
doc/source/specs/pike/template.rst View File

@@ -1,397 +0,0 @@
1
-..
2
- This work is licensed under a Creative Commons Attribution 3.0 Unported
3
- License.
4
-
5
- http://creativecommons.org/licenses/by/3.0/legalcode
6
-
7
-==========================================
8
-Example Spec - The title of your blueprint
9
-==========================================
10
-
11
-Include the URL of your launchpad blueprint:
12
-
13
-https://blueprints.launchpad.net/nova/+spec/example
14
-
15
-Introduction paragraph -- why are we doing anything? A single paragraph of
16
-prose that operators can understand. The title and this first paragraph
17
-should be used as the subject line and body of the commit message
18
-respectively.
19
-
20
-Some notes about the nova-spec and blueprint process:
21
-
22
-* Not all blueprints need a spec. For more information see
23
-  https://docs.openstack.org/nova/latest/blueprints.html
24
-
25
-* The aim of this document is first to define the problem we need to solve,
26
-  and second agree the overall approach to solve that problem.
27
-
28
-* This is not intended to be extensive documentation for a new feature.
29
-  For example, there is no need to specify the exact configuration changes,
30
-
31
-  nor the exact details of any DB model changes. But you should still define
32
-  that such changes are required, and be clear on how that will affect
33
-  upgrades.
34
-
35
-* You should aim to get your spec approved before writing your code.
36
-  While you are free to write prototypes and code before getting your spec
37
-  approved, its possible that the outcome of the spec review process leads
38
-  you towards a fundamentally different solution than you first envisaged.
39
-
40
-* But, API changes are held to a much higher level of scrutiny.
41
-  As soon as an API change merges, we must assume it could be in production
42
-  somewhere, and as such, we then need to support that API change forever.
43
-  To avoid getting that wrong, we do want lots of details about API changes
44
-  upfront.
45
-
46
-Some notes about using this template:
47
-
48
-* Your spec should be in ReSTructured text, like this template.
49
-
50
-* Please wrap text at 79 columns.
51
-
52
-* The filename in the git repository should match the launchpad URL, for
53
-  example a URL of: https://blueprints.launchpad.net/nova/+spec/awesome-thing
54
-  should be named awesome-thing.rst
55
-
56
-* Please do not delete any of the sections in this template.  If you have
57
-  nothing to say for a whole section, just write: None
58
-
59
-* For help with syntax, see http://sphinx-doc.org/rest.html
60
-
61
-* To test out your formatting, build the docs using tox and see the generated
62
-  HTML file in doc/build/html/specs/<path_of_your_file>
63
-
64
-* If you would like to provide a diagram with your spec, ascii diagrams are
65
-  required.  http://asciiflow.com/ is a very nice tool to assist with making
66
-  ascii diagrams.  The reason for this is that the tool used to review specs is
67
-  based purely on plain text.  Plain text will allow review to proceed without
68
-  having to look at additional files which can not be viewed in gerrit.  It
69
-  will also allow inline feedback on the diagram itself.
70
-
71
-* If your specification proposes any changes to the Nova REST API such
72
-  as changing parameters which can be returned or accepted, or even
73
-  the semantics of what happens when a client calls into the API, then
74
-  you should add the APIImpact flag to the commit message. Specifications with
75
-  the APIImpact flag can be found with the following query:
76
-
77
-  https://review.openstack.org/#/q/status:open+project:openstack/nova-specs+message:apiimpact,n,z
78
-
79
-
80
-Problem description
81
-===================
82
-
83
-A detailed description of the problem. What problem is this blueprint
84
-addressing?
85
-
86
-Use Cases
87
----------
88
-
89
-What use cases does this address? What impact on actors does this change have?
90
-Ensure you are clear about the actors in each use case: Developer, End User,
91
-Deployer etc.
92
-
93
-Proposed change
94
-===============
95
-
96
-Here is where you cover the change you propose to make in detail. How do you
97
-propose to solve this problem?
98
-
99
-If this is one part of a larger effort make it clear where this piece ends. In
100
-other words, what's the scope of this effort?
101
-
102
-At this point, if you would like to just get feedback on if the problem and
103
-proposed change fit in nova, you can stop here and post this for review to get
104
-preliminary feedback. If so please say:
105
-Posting to get preliminary feedback on the scope of this spec.
106
-
107
-Alternatives
108
-------------
109
-
110
-What other ways could we do this thing? Why aren't we using those? This doesn't
111
-have to be a full literature review, but it should demonstrate that thought has
112
-been put into why the proposed solution is an appropriate one.
113
-
114
-Data model impact
115
------------------
116
-
117
-Changes which require modifications to the data model often have a wider impact
118
-on the system.  The community often has strong opinions on how the data model
119
-should be evolved, from both a functional and performance perspective. It is
120
-therefore important to capture and gain agreement as early as possible on any
121
-proposed changes to the data model.
122
-
123
-Questions which need to be addressed by this section include:
124
-
125
-* What new data objects and/or database schema changes is this going to
126
-  require?
127
-
128
-* What database migrations will accompany this change.
129
-
130
-* How will the initial set of new data objects be generated, for example if you
131
-  need to take into account existing instances, or modify other existing data
132
-  describe how that will work.
133
-
134
-REST API impact
135
----------------
136
-
137
-Each API method which is either added or changed should have the following
138
-
139
-* Specification for the method
140
-
141
-  * A description of what the method does suitable for use in
142
-    user documentation
143
-
144
-  * Method type (POST/PUT/GET/DELETE)
145
-
146
-  * Normal http response code(s)
147
-
148
-  * Expected error http response code(s)
149
-
150
-    * A description for each possible error code should be included
151
-      describing semantic errors which can cause it such as
152
-      inconsistent parameters supplied to the method, or when an
153
-      instance is not in an appropriate state for the request to
154
-      succeed. Errors caused by syntactic problems covered by the JSON
155
-      schema definition do not need to be included.
156
-
157
-  * URL for the resource
158
-
159
-    * URL should not include underscores, and use hyphens instead.
160
-
161
-  * Parameters which can be passed via the url
162
-
163
-  * JSON schema definition for the request body data if allowed
164
-
165
-    * Field names should use snake_case style, not CamelCase or MixedCase
166
-      style.
167
-
168
-  * JSON schema definition for the response body data if any
169
-
170
-    * Field names should use snake_case style, not CamelCase or MixedCase
171
-      style.
172
-
173
-* Example use case including typical API samples for both data supplied
174
-  by the caller and the response
175
-
176
-* Discuss any policy changes, and discuss what things a deployer needs to
177
-  think about when defining their policy.
178
-
179
-Example JSON schema definitions can be found in the Nova tree
180
-http://git.openstack.org/cgit/openstack/nova/tree/nova/api/openstack/compute/schemas
181
-
182
-Note that the schema should be defined as restrictively as
183
-possible. Parameters which are required should be marked as such and
184
-only under exceptional circumstances should additional parameters
185
-which are not defined in the schema be permitted (eg
186
-additionaProperties should be False).
187
-
188
-Reuse of existing predefined parameter types such as regexps for
189
-passwords and user defined names is highly encouraged.
190
-
191
-Security impact
192
----------------
193
-
194
-Describe any potential security impact on the system.  Some of the items to
195
-consider include:
196
-
197
-* Does this change touch sensitive data such as tokens, keys, or user data?
198
-
199
-* Does this change alter the API in a way that may impact security, such as
200
-  a new way to access sensitive information or a new way to login?
201
-
202
-* Does this change involve cryptography or hashing?
203
-
204
-* Does this change require the use of sudo or any elevated privileges?
205
-
206
-* Does this change involve using or parsing user-provided data? This could
207
-  be directly at the API level or indirectly such as changes to a cache layer.
208
-
209
-* Can this change enable a resource exhaustion attack, such as allowing a
210
-  single API interaction to consume significant server resources? Some examples
211
-  of this include launching subprocesses for each connection, or entity
212
-  expansion attacks in XML.
213
-
214
-For more detailed guidance, please see the OpenStack Security Guidelines as
215
-a reference (https://wiki.openstack.org/wiki/Security/Guidelines).  These
216
-guidelines are a work in progress and are designed to help you identify
217
-security best practices.  For further information, feel free to reach out
218
-to the OpenStack Security Group at openstack-security@lists.openstack.org.
219
-
220
-Notifications impact
221
---------------------
222
-
223
-Please specify any changes to notifications. Be that an extra notification,
224
-changes to an existing notification, or removing a notification.
225
-
226
-Other end user impact
227
----------------------
228
-
229
-Aside from the API, are there other ways a user will interact with this
230
-feature?
231
-
232
-* Does this change have an impact on python-novaclient? What does the user
233
-  interface there look like?
234
-
235
-Performance Impact
236
-------------------
237
-
238
-Describe any potential performance impact on the system, for example
239
-how often will new code be called, and is there a major change to the calling
240
-pattern of existing code.
241
-
242
-Examples of things to consider here include:
243
-
244
-* A periodic task might look like a small addition but if it calls conductor or
245
-  another service the load is multiplied by the number of nodes in the system.
246
-
247
-* Scheduler filters get called once per host for every instance being created,
248
-  so any latency they introduce is linear with the size of the system.
249
-
250
-* A small change in a utility function or a commonly used decorator can have a
251
-  large impacts on performance.
252
-
253
-* Calls which result in a database queries (whether direct or via conductor)
254
-  can have a profound impact on performance when called in critical sections of
255
-  the code.
256
-
257
-* Will the change include any locking, and if so what considerations are there
258
-  on holding the lock?
259
-
260
-Other deployer impact
261
----------------------
262
-
263
-Discuss things that will affect how you deploy and configure OpenStack
264
-that have not already been mentioned, such as:
265
-
266
-* What config options are being added? Should they be more generic than
267
-  proposed (for example a flag that other hypervisor drivers might want to
268
-  implement as well)? Are the default values ones which will work well in
269
-  real deployments?
270
-
271
-* Is this a change that takes immediate effect after its merged, or is it
272
-  something that has to be explicitly enabled?
273
-
274
-* If this change is a new binary, how would it be deployed?
275
-
276
-* Please state anything that those doing continuous deployment, or those
277
-  upgrading from the previous release, need to be aware of. Also describe
278
-  any plans to deprecate configuration values or features.  For example, if we
279
-  change the directory name that instances are stored in, how do we handle
280
-  instance directories created before the change landed?  Do we move them?  Do
281
-  we have a special case in the code? Do we assume that the operator will
282
-  recreate all the instances in their cloud?
283
-
284
-Developer impact
285
-----------------
286
-
287
-Discuss things that will affect other developers working on OpenStack,
288
-such as:
289
-
290
-* If the blueprint proposes a change to the driver API, discussion of how
291
-  other hypervisors would implement the feature is required.
292
-
293
-
294
-Implementation
295
-==============
296
-
297
-Assignee(s)
298
------------
299
-
300
-Who is leading the writing of the code? Or is this a blueprint where you're
301
-throwing it out there to see who picks it up?
302
-
303
-If more than one person is working on the implementation, please designate the
304
-primary author and contact.
305
-
306
-Primary assignee:
307
-  <launchpad-id or None>
308
-
309
-Other contributors:
310
-  <launchpad-id or None>
311
-
312
-Work Items
313
-----------
314
-
315
-Work items or tasks -- break the feature up into the things that need to be
316
-done to implement it. Those parts might end up being done by different people,
317
-but we're mostly trying to understand the timeline for implementation.
318
-
319
-
320
-Dependencies
321
-============
322
-
323
-* Include specific references to specs and/or blueprints in nova, or in other
324
-  projects, that this one either depends on or is related to.
325
-
326
-* If this requires functionality of another project that is not currently used
327
-  by Nova (such as the glance v2 API when we previously only required v1),
328
-  document that fact.
329
-
330
-* Does this feature require any new library dependencies or code otherwise not
331
-  included in OpenStack? Or does it depend on a specific version of library?
332
-
333
-
334
-Testing
335
-=======
336
-
337
-Please discuss the important scenarios needed to test here, as well as
338
-specific edge cases we should be ensuring work correctly. For each
339
-scenario please specify if this requires specialized hardware, a full
340
-openstack environment, or can be simulated inside the Nova tree.
341
-
342
-Please discuss how the change will be tested. We especially want to know what
343
-tempest tests will be added. It is assumed that unit test coverage will be
344
-added so that doesn't need to be mentioned explicitly, but discussion of why
345
-you think unit tests are sufficient and we don't need to add more tempest
346
-tests would need to be included.
347
-
348
-Is this untestable in gate given current limitations (specific hardware /
349
-software configurations available)? If so, are there mitigation plans (3rd
350
-party testing, gate enhancements, etc).
351
-
352
-
353
-Documentation Impact
354
-====================
355
-
356
-Which audiences are affected most by this change, and which documentation
357
-titles on docs.openstack.org should be updated because of this change? Don't
358
-repeat details discussed above, but reference them here in the context of
359
-documentation for multiple audiences. For example, the Operations Guide targets
360
-cloud operators, and the End User Guide would need to be updated if the change
361
-offers a new feature available through the CLI or dashboard. If a config option
362
-changes or is deprecated, note here that the documentation needs to be updated
363
-to reflect this specification's change.
364
-
365
-References
366
-==========
367
-
368
-Please add any useful references here. You are not required to have any
369
-reference. Moreover, this specification should still make sense when your
370
-references are unavailable. Examples of what you could include are:
371
-
372
-* Links to mailing list or IRC discussions
373
-
374
-* Links to notes from a summit session
375
-
376
-* Links to relevant research, if appropriate
377
-
378
-* Related specifications as appropriate (e.g.  if it's an EC2 thing, link the
379
-  EC2 docs)
380
-
381
-* Anything else you feel it is worthwhile to refer to
382
-
383
-
384
-History
385
-=======
386
-
387
-Optional section intended to be used each time the spec is updated to describe
388
-new design, API or any database schema updated. Useful to let reader understand
389
-what's happened along the time.
390
-
391
-.. list-table:: Revisions
392
-   :header-rows: 1
393
-
394
-   * - Release Name
395
-     - Description
396
-   * - Pike
397
-     - Introduced

+ 0
- 0
doc/source/specs/queens/approved/.dummy View File


+ 0
- 0
doc/source/specs/queens/implemented/.dummy View File


+ 0
- 26
doc/source/specs/queens/index.rst View File

@@ -1,26 +0,0 @@
1
-==================================
2
-Nova-dpm specifications for Queens
3
-==================================
4
-
5
-Template:
6
-
7
-.. toctree::
8
-   :maxdepth: 1
9
-
10
-   Specification Template (Queens release) <template>
11
-
12
-Specs implemented in Queens:
13
-
14
-.. toctree::
15
-   :glob:
16
-   :maxdepth: 1
17
-
18
-   implemented/*
19
-
20
-Specs proposed / approved for Queens:
21
-
22
-.. toctree::
23
-   :glob:
24
-   :maxdepth: 1
25
-
26
-   approved/*

+ 0
- 397
doc/source/specs/queens/template.rst View File

@@ -1,397 +0,0 @@
1
-..
2
- This work is licensed under a Creative Commons Attribution 3.0 Unported
3
- License.
4
-
5
- http://creativecommons.org/licenses/by/3.0/legalcode
6
-
7
-==========================================
8
-Example Spec - The title of your blueprint
9
-==========================================
10
-
11
-Include the URL of your launchpad blueprint:
12
-
13
-https://blueprints.launchpad.net/nova/+spec/example
14
-
15
-Introduction paragraph -- why are we doing anything? A single paragraph of
16
-prose that operators can understand. The title and this first paragraph
17
-should be used as the subject line and body of the commit message
18
-respectively.
19
-
20
-Some notes about the nova-spec and blueprint process:
21
-
22
-* Not all blueprints need a spec. For more information see
23
-  https://docs.openstack.org/nova/latest/blueprints.html
24
-
25
-* The aim of this document is first to define the problem we need to solve,
26
-  and second agree the overall approach to solve that problem.
27
-
28
-* This is not intended to be extensive documentation for a new feature.
29
-  For example, there is no need to specify the exact configuration changes,
30
-
31
-  nor the exact details of any DB model changes. But you should still define
32
-  that such changes are required, and be clear on how that will affect
33
-  upgrades.
34
-
35
-* You should aim to get your spec approved before writing your code.
36
-  While you are free to write prototypes and code before getting your spec
37
-  approved, its possible that the outcome of the spec review process leads
38
-  you towards a fundamentally different solution than you first envisaged.
39
-
40
-* But, API changes are held to a much higher level of scrutiny.
41
-  As soon as an API change merges, we must assume it could be in production
42
-  somewhere, and as such, we then need to support that API change forever.
43
-  To avoid getting that wrong, we do want lots of details about API changes
44
-  upfront.
45
-
46
-Some notes about using this template:
47
-
48
-* Your spec should be in ReSTructured text, like this template.
49
-
50
-* Please wrap text at 79 columns.
51
-
52
-* The filename in the git repository should match the launchpad URL, for
53
-  example a URL of: https://blueprints.launchpad.net/nova/+spec/awesome-thing
54
-  should be named awesome-thing.rst
55
-
56
-* Please do not delete any of the sections in this template.  If you have
57
-  nothing to say for a whole section, just write: None
58
-
59
-* For help with syntax, see http://sphinx-doc.org/rest.html
60
-
61
-* To test out your formatting, build the docs using tox and see the generated
62
-  HTML file in doc/build/html/specs/<path_of_your_file>
63
-
64
-* If you would like to provide a diagram with your spec, ascii diagrams are
65
-  required.  http://asciiflow.com/ is a very nice tool to assist with making
66
-  ascii diagrams.  The reason for this is that the tool used to review specs is
67
-  based purely on plain text.  Plain text will allow review to proceed without
68
-  having to look at additional files which can not be viewed in gerrit.  It
69
-  will also allow inline feedback on the diagram itself.
70
-
71
-* If your specification proposes any changes to the Nova REST API such
72
-  as changing parameters which can be returned or accepted, or even
73
-  the semantics of what happens when a client calls into the API, then
74
-  you should add the APIImpact flag to the commit message. Specifications with
75
-  the APIImpact flag can be found with the following query:
76
-
77
-  https://review.openstack.org/#/q/status:open+project:openstack/nova-specs+message:apiimpact,n,z
78
-
79
-
80
-Problem description
81
-===================
82
-
83
-A detailed description of the problem. What problem is this blueprint
84
-addressing?
85
-
86
-Use Cases
87
----------
88
-
89
-What use cases does this address? What impact on actors does this change have?
90
-Ensure you are clear about the actors in each use case: Developer, End User,
91
-Deployer etc.
92
-
93
-Proposed change
94
-===============
95
-
96
-Here is where you cover the change you propose to make in detail. How do you
97
-propose to solve this problem?
98
-
99
-If this is one part of a larger effort make it clear where this piece ends. In
100
-other words, what's the scope of this effort?
101
-
102
-At this point, if you would like to just get feedback on if the problem and
103
-proposed change fit in nova, you can stop here and post this for review to get
104
-preliminary feedback. If so please say:
105
-Posting to get preliminary feedback on the scope of this spec.
106
-
107
-Alternatives
108
-------------
109
-
110
-What other ways could we do this thing? Why aren't we using those? This doesn't
111
-have to be a full literature review, but it should demonstrate that thought has
112
-been put into why the proposed solution is an appropriate one.
113
-
114
-Data model impact
115
------------------
116
-
117
-Changes which require modifications to the data model often have a wider impact
118
-on the system.  The community often has strong opinions on how the data model
119
-should be evolved, from both a functional and performance perspective. It is
120
-therefore important to capture and gain agreement as early as possible on any
121
-proposed changes to the data model.
122
-
123
-Questions which need to be addressed by this section include:
124
-
125
-* What new data objects and/or database schema changes is this going to
126
-  require?
127
-
128
-* What database migrations will accompany this change.
129
-
130
-* How will the initial set of new data objects be generated, for example if you
131
-  need to take into account existing instances, or modify other existing data
132
-  describe how that will work.
133
-
134
-REST API impact
135
----------------
136
-
137
-Each API method which is either added or changed should have the following
138
-
139
-* Specification for the method
140
-
141
-  * A description of what the method does suitable for use in
142
-    user documentation
143
-
144
-  * Method type (POST/PUT/GET/DELETE)
145
-
146
-  * Normal http response code(s)
147
-
148
-  * Expected error http response code(s)
149
-
150
-    * A description for each possible error code should be included
151
-      describing semantic errors which can cause it such as
152
-      inconsistent parameters supplied to the method, or when an
153
-      instance is not in an appropriate state for the request to
154
-      succeed. Errors caused by syntactic problems covered by the JSON
155
-      schema definition do not need to be included.
156
-
157
-  * URL for the resource
158
-
159
-    * URL should not include underscores, and use hyphens instead.
160
-
161
-  * Parameters which can be passed via the url
162
-
163
-  * JSON schema definition for the request body data if allowed
164
-
165
-    * Field names should use snake_case style, not CamelCase or MixedCase
166
-      style.
167
-
168
-  * JSON schema definition for the response body data if any
169
-
170
-    * Field names should use snake_case style, not CamelCase or MixedCase
171
-      style.
172
-
173
-* Example use case including typical API samples for both data supplied
174
-  by the caller and the response
175
-
176
-* Discuss any policy changes, and discuss what things a deployer needs to
177
-  think about when defining their policy.
178
-
179
-Example JSON schema definitions can be found in the Nova tree
180
-http://git.openstack.org/cgit/openstack/nova/tree/nova/api/openstack/compute/schemas
181
-
182
-Note that the schema should be defined as restrictively as
183
-possible. Parameters which are required should be marked as such and
184
-only under exceptional circumstances should additional parameters
185
-which are not defined in the schema be permitted (eg
186
-additionaProperties should be False).
187
-
188
-Reuse of existing predefined parameter types such as regexps for
189
-passwords and user defined names is highly encouraged.
190
-
191
-Security impact
192
----------------
193
-
194
-Describe any potential security impact on the system.  Some of the items to
195
-consider include:
196
-
197
-* Does this change touch sensitive data such as tokens, keys, or user data?
198
-
199
-* Does this change alter the API in a way that may impact security, such as
200
-  a new way to access sensitive information or a new way to login?
201
-
202
-* Does this change involve cryptography or hashing?
203
-
204
-* Does this change require the use of sudo or any elevated privileges?
205
-
206
-* Does this change involve using or parsing user-provided data? This could
207
-  be directly at the API level or indirectly such as changes to a cache layer.
208
-
209
-* Can this change enable a resource exhaustion attack, such as allowing a
210
-  single API interaction to consume significant server resources? Some examples
211
-  of this include launching subprocesses for each connection, or entity
212
-  expansion attacks in XML.
213
-
214
-For more detailed guidance, please see the OpenStack Security Guidelines as
215
-a reference (https://wiki.openstack.org/wiki/Security/Guidelines).  These
216
-guidelines are a work in progress and are designed to help you identify
217
-security best practices.  For further information, feel free to reach out
218
-to the OpenStack Security Group at openstack-security@lists.openstack.org.
219
-
220
-Notifications impact
221
---------------------
222
-
223
-Please specify any changes to notifications. Be that an extra notification,
224
-changes to an existing notification, or removing a notification.
225
-
226
-Other end user impact
227
----------------------
228
-
229
-Aside from the API, are there other ways a user will interact with this
230
-feature?
231
-
232
-* Does this change have an impact on python-novaclient? What does the user
233
-  interface there look like?
234
-
235
-Performance Impact
236
-------------------
237
-
238
-Describe any potential performance impact on the system, for example
239
-how often will new code be called, and is there a major change to the calling
240
-pattern of existing code.
241
-
242
-Examples of things to consider here include:
243
-
244
-* A periodic task might look like a small addition but if it calls conductor or
245
-  another service the load is multiplied by the number of nodes in the system.
246
-
247
-* Scheduler filters get called once per host for every instance being created,
248
-  so any latency they introduce is linear with the size of the system.
249
-
250
-* A small change in a utility function or a commonly used decorator can have a
251
-  large impacts on performance.
252
-
253
-* Calls which result in a database queries (whether direct or via conductor)
254
-  can have a profound impact on performance when called in critical sections of
255
-  the code.
256
-
257
-* Will the change include any locking, and if so what considerations are there
258
-  on holding the lock?
259
-
260
-Other deployer impact
261
----------------------
262
-
263
-Discuss things that will affect how you deploy and configure OpenStack
264
-that have not already been mentioned, such as:
265
-
266
-* What config options are being added? Should they be more generic than
267
-  proposed (for example a flag that other hypervisor drivers might want to
268
-  implement as well)? Are the default values ones which will work well in
269
-  real deployments?
270
-
271
-* Is this a change that takes immediate effect after its merged, or is it
272
-  something that has to be explicitly enabled?
273
-
274
-* If this change is a new binary, how would it be deployed?
275
-
276
-* Please state anything that those doing continuous deployment, or those
277
-  upgrading from the previous release, need to be aware of. Also describe
278
-  any plans to deprecate configuration values or features.  For example, if we
279
-  change the directory name that instances are stored in, how do we handle
280
-  instance directories created before the change landed?  Do we move them?  Do
281
-  we have a special case in the code? Do we assume that the operator will
282
-  recreate all the instances in their cloud?
283
-
284
-Developer impact
285
-----------------
286
-
287
-Discuss things that will affect other developers working on OpenStack,
288
-such as:
289
-
290
-* If the blueprint proposes a change to the driver API, discussion of how
291
-  other hypervisors would implement the feature is required.
292
-
293
-
294
-Implementation
295
-==============
296
-
297
-Assignee(s)
298
------------
299
-
300
-Who is leading the writing of the code? Or is this a blueprint where you're
301
-throwing it out there to see who picks it up?
302
-
303
-If more than one person is working on the implementation, please designate the
304
-primary author and contact.
305
-
306
-Primary assignee:
307
-  <launchpad-id or None>
308
-
309
-Other contributors:
310
-  <launchpad-id or None>
311
-
312
-Work Items
313
-----------
314
-
315
-Work items or tasks -- break the feature up into the things that need to be
316
-done to implement it. Those parts might end up being done by different people,
317
-but we're mostly trying to understand the timeline for implementation.
318
-
319
-
320
-Dependencies
321
-============
322
-
323
-* Include specific references to specs and/or blueprints in nova, or in other
324
-  projects, that this one either depends on or is related to.
325
-
326
-* If this requires functionality of another project that is not currently used
327
-  by Nova (such as the glance v2 API when we previously only required v1),
328
-  document that fact.
329
-
330
-* Does this feature require any new library dependencies or code otherwise not
331
-  included in OpenStack? Or does it depend on a specific version of library?
332
-
333
-
334
-Testing
335
-=======
336
-
337
-Please discuss the important scenarios needed to test here, as well as
338
-specific edge cases we should be ensuring work correctly. For each
339
-scenario please specify if this requires specialized hardware, a full
340
-openstack environment, or can be simulated inside the Nova tree.
341
-
342
-Please discuss how the change will be tested. We especially want to know what
343
-tempest tests will be added. It is assumed that unit test coverage will be
344
-added so that doesn't need to be mentioned explicitly, but discussion of why
345
-you think unit tests are sufficient and we don't need to add more tempest
346
-tests would need to be included.
347
-
348
-Is this untestable in gate given current limitations (specific hardware /
349
-software configurations available)? If so, are there mitigation plans (3rd
350
-party testing, gate enhancements, etc).
351
-
352
-
353
-Documentation Impact
354
-====================
355
-
356
-Which audiences are affected most by this change, and which documentation
357
-titles on docs.openstack.org should be updated because of this change? Don't
358
-repeat details discussed above, but reference them here in the context of
359
-documentation for multiple audiences. For example, the Operations Guide targets
360
-cloud operators, and the End User Guide would need to be updated if the change
361
-offers a new feature available through the CLI or dashboard. If a config option
362
-changes or is deprecated, note here that the documentation needs to be updated
363
-to reflect this specification's change.
364
-
365
-References
366
-==========
367
-
368
-Please add any useful references here. You are not required to have any
369
-reference. Moreover, this specification should still make sense when your
370
-references are unavailable. Examples of what you could include are:
371
-
372
-* Links to mailing list or IRC discussions
373
-
374
-* Links to notes from a summit session
375
-
376
-* Links to relevant research, if appropriate
377
-
378
-* Related specifications as appropriate (e.g.  if it's an EC2 thing, link the
379
-  EC2 docs)
380
-
381
-* Anything else you feel it is worthwhile to refer to
382
-
383
-
384
-History
385
-=======
386
-
387
-Optional section intended to be used each time the spec is updated to describe
388
-new design, API or any database schema updated. Useful to let reader understand
389
-what's happened along the time.
390
-
391
-.. list-table:: Revisions
392
-   :header-rows: 1
393
-
394
-   * - Release Name
395
-     - Description
396
-   * - Queens
397
-     - Introduced

doc/source/specs/ocata/template.rst → doc/source/specs/template.rst View File


Loading…
Cancel
Save