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