Browse Source

This is the inital cookbook versioning doc

This is to outline the cookbook versioning guidelines.

Change-Id: I2895939495330517c9f67d8e350ab540811ef5a1
JJ Asghar 4 years ago
parent
commit
4fe49f3f7c
6 changed files with 210 additions and 668 deletions
  1. 5
    2
      README.rst
  2. 2
    1
      doc/source/conf.py
  3. 3
    19
      doc/source/index.rst
  4. 0
    323
      specs/icehouse/template.rst
  5. 200
    0
      specs/juno/common/cookbook-versioning.rst
  6. 0
    323
      specs/juno/template.rst

+ 5
- 2
README.rst View File

@@ -3,8 +3,8 @@ OpenStack-chef Specifications
3 3
 ==================================
4 4
 
5 5
 This git repository is used to hold approved design specifications for additions
6
-to the openstack-chef project.  Reviews of the specs are done in gerrit, using a similar
7
-workflow to how we review and merge changes to the code itself.
6
+to the openstack-chef project.  Reviews of the specifications are done in gerrit,
7
+using a similar workflow to how we review and merge changes to the code itself.
8 8
 
9 9
 The layout of this repository is::
10 10
 
@@ -16,6 +16,9 @@ Specifications are proposed for a given release by adding them to the
16 16
 `specs/<release>` directory and posting it for review.  The implementation
17 17
 status of a blueprint for a given release can be found by looking at the
18 18
 blueprint in launchpad.  Not all approved blueprints will get fully implemented.
19
+Use the Common cookbook directory for specifications that effect multiple
20
+cookbooks.  Once the specification is approved and merged, the LaunchPad
21
+blueprint will be updated accordingly.
19 22
 
20 23
 Specifications have to be re-proposed for every release.  The review may be
21 24
 quick, but even if something was previously approved, it should be re-reviewed

+ 2
- 1
doc/source/conf.py View File

@@ -63,7 +63,8 @@ copyright = u'2014, Chef for Openstack Team'
63 63
 
64 64
 # List of patterns, relative to source directory, that match files and
65 65
 # directories to ignore when looking for source files.
66
-exclude_patterns = ['_build']
66
+exclude_patterns = ['_build',
67
+                    '**template.rst']
67 68
 
68 69
 # The reST default role (used for this markup: `text`) to use for all documents.
69 70
 #default_role = None

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

@@ -4,29 +4,13 @@
4 4
 Openstack for Chef Project Specifications
5 5
 =========================================
6 6
 
7
-Contents:
7
+Juno specs:
8 8
 
9 9
 .. toctree::
10 10
    :glob:
11
-   :maxdepth: 1
11
+   :maxdepth: 4
12 12
 
13
-   specs/*
14
-
15
-Juno approved specs:
16
-
17
-.. toctree::
18
-   :glob:
19
-   :maxdepth: 1
20
-
21
-   specs/juno/*
22
-
23
-Icehouse approved specs:
24
-
25
-.. toctree::
26
-   :glob:
27
-   :maxdepth: 1
28
-
29
-   specs/icehouse/*
13
+   specs/juno/**
30 14
 
31 15
 ==================
32 16
 Indices and tables

+ 0
- 323
specs/icehouse/template.rst View File

@@ -1,323 +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/openstack-chef/+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 using this template:
21
-
22
-* Your spec should be in ReSTructured text, like this template.
23
-
24
-* Please wrap text at 79 columns.
25
-
26
-* The filename in the git repository should match the launchpad URL, for
27
-  example a URL of: https://blueprints.launchpad.net/openstack-chef/+spec/awesome-thing
28
-  should be named awesome-thing.rst
29
-
30
-* Please do not delete any of the sections in this template.  If you have
31
-  nothing to say for a whole section, just write: None
32
-
33
-* For help with syntax, see http://sphinx-doc.org/rest.html
34
-
35
-* To test out your formatting, build the docs using tox and see the generated
36
-  HTML file in doc/build/html/specs/<path_of_your_file>
37
-
38
-* If you would like to provide a diagram with your spec, ascii diagrams are
39
-  required.  http://asciiflow.com/ is a very nice tool to assist with making
40
-  ascii diagrams.  The reason for this is that the tool used to review specs is
41
-  based purely on plain text.  Plain text will allow review to proceed without
42
-  having to look at additional files which can not be viewed in gerrit.  It
43
-  will also allow inline feedback on the diagram itself.
44
-
45
-Problem description
46
-===================
47
-
48
-A detailed description of the problem:
49
-
50
-* For a new feature this might be use cases. Ensure you are clear about the
51
-  actors in each use case: End User vs Deployer
52
-
53
-* For a major reworking of something existing it would describe the
54
-  problems in that feature that are being addressed.
55
-
56
-
57
-Proposed change
58
-===============
59
-
60
-Here is where you cover the change you propose to make in detail. How do you
61
-propose to solve this problem?
62
-
63
-If this is one part of a larger effort make it clear where this piece ends. In
64
-other words, what's the scope of this effort?
65
-
66
-Alternatives
67
-------------
68
-
69
-What other ways could we do this thing? Why aren't we using those? This doesn't
70
-have to be a full literature review, but it should demonstrate that thought has
71
-been put into why the proposed solution is an appropriate one.
72
-
73
-Data model impact
74
------------------
75
-
76
-Changes which require modifications to the data model often have a wider impact
77
-on the system.  The community often has strong opinions on how the data model
78
-should be evolved, from both a functional and performance perspective. It is
79
-therefore important to capture and gain agreement as early as possible on any
80
-proposed changes to the data model.
81
-
82
-Questions which need to be addressed by this section include:
83
-
84
-* What new data objects and/or database schema changes is this going to
85
-  require?
86
-
87
-* What database migrations will accompany this change.
88
-
89
-* How will the initial set of new data objects be generated, for example if you
90
-  need to take into account existing instances, or modify other existing data
91
-  describe how that will work.
92
-
93
-REST API impact
94
----------------
95
-
96
-Each API method which is either added or changed should have the following
97
-
98
-* Specification for the method
99
-
100
-  * A description of what the method does suitable for use in
101
-    user documentation
102
-
103
-  * Method type (POST/PUT/GET/DELETE)
104
-
105
-  * Normal http response code(s)
106
-
107
-  * Expected error http response code(s)
108
-
109
-    * A description for each possible error code should be included
110
-      describing semantic errors which can cause it such as
111
-      inconsistent parameters supplied to the method, or when an
112
-      instance is not in an appropriate state for the request to
113
-      succeed. Errors caused by syntactic problems covered by the JSON
114
-      schema defintion do not need to be included.
115
-
116
-  * URL for the resource
117
-
118
-  * Parameters which can be passed via the url
119
-
120
-  * JSON schema definition for the body data if allowed
121
-
122
-  * JSON schema definition for the response data if any
123
-
124
-* Example use case including typical API samples for both data supplied
125
-  by the caller and the response
126
-
127
-* Discuss any policy changes, and discuss what things a deployer needs to
128
-  think about when defining their policy.
129
-
130
-Example JSON schema definitions can be found in the openstack-chef tree
131
-http://git.openstack.org/cgit/openstack/openstack-chef/tree/openstack-chef/api/openstack/compute/schemas/v3
132
-
133
-Note that the schema should be defined as restrictively as
134
-possible. Parameters which are required should be marked as such and
135
-only under exceptional circumstances should additional parameters
136
-which are not defined in the schema be permitted (eg
137
-additionaProperties should be False).
138
-
139
-Reuse of existing predefined parameter types such as regexps for
140
-passwords and user defined names is highly encouraged.
141
-
142
-Security impact
143
----------------
144
-
145
-Describe any potential security impact on the system.  Some of the items to
146
-consider include:
147
-
148
-* Does this change touch sensitive data such as tokens, keys, or user data?
149
-
150
-* Does this change alter the API in a way that may impact security, such as
151
-  a new way to access sensitive information or a new way to login?
152
-
153
-* Does this change involve cryptography or hashing?
154
-
155
-* Does this change require the use of sudo or any elevated privileges?
156
-
157
-* Does this change involve using or parsing user-provided data? This could
158
-  be directly at the API level or indirectly such as changes to a cache layer.
159
-
160
-* Can this change enable a resource exhaustion attack, such as allowing a
161
-  single API interaction to consume significant server resources? Some examples
162
-  of this include launching subprocesses for each connection, or entity
163
-  expansion attacks in XML.
164
-
165
-For more detailed guidance, please see the OpenStack Security Guidelines as
166
-a reference (https://wiki.openstack.org/wiki/Security/Guidelines).  These
167
-guidelines are a work in progress and are designed to help you identify
168
-security best practices.  For further information, feel free to reach out
169
-to the OpenStack Security Group at openstack-security@lists.openstack.org.
170
-
171
-Notifications impact
172
---------------------
173
-
174
-Please specify any changes to notifications. Be that an extra notification,
175
-changes to an existing notification, or removing a notification.
176
-
177
-Other end user impact
178
----------------------
179
-
180
-Aside from the API, are there other ways a user will interact with this
181
-feature?
182
-
183
-* Does this change have an impact on python-openstack-chefclient? What does the user
184
-  interface there look like?
185
-
186
-Performance Impact
187
-------------------
188
-
189
-Describe any potential performance impact on the system, for example
190
-how often will new code be called, and is there a major change to the calling
191
-pattern of existing code.
192
-
193
-Examples of things to consider here include:
194
-
195
-* A periodic task might look like a small addition but if it calls conductor or
196
-  another service the load is multiplied by the number of nodes in the system.
197
-
198
-* Scheduler filters get called once per host for every instance being created,
199
-  so any latency they introduce is linear with the size of the system.
200
-
201
-* A small change in a utility function or a commonly used decorator can have a
202
-  large impacts on performance.
203
-
204
-* Calls which result in a database queries (whether direct or via conductor)
205
-  can have a profound impact on performance when called in critical sections of
206
-  the code.
207
-
208
-* Will the change include any locking, and if so what considerations are there
209
-  on holding the lock?
210
-
211
-Other deployer impact
212
----------------------
213
-
214
-Discuss things that will affect how you deploy and configure OpenStack
215
-that have not already been mentioned, such as:
216
-
217
-* What config options are being added? Should they be more generic than
218
-  proposed (for example a flag that other hypervisor drivers might want to
219
-  implement as well)? Are the default values ones which will work well in
220
-  real deployments?
221
-
222
-* Is this a change that takes immediate effect after its merged, or is it
223
-  something that has to be explicitly enabled?
224
-
225
-* If this change is a new binary, how would it be deployed?
226
-
227
-* Please state anything that those doing continuous deployment, or those
228
-  upgrading from the previous release, need to be aware of. Also describe
229
-  any plans to deprecate configuration values or features.  For example, if we
230
-  change the directory name that instances are stored in, how do we handle
231
-  instance directories created before the change landed?  Do we move them?  Do
232
-  we have a special case in the code? Do we assume that the operator will
233
-  recreate all the instances in their cloud?
234
-
235
-Developer impact
236
-----------------
237
-
238
-Discuss things that will affect other developers working on OpenStack,
239
-such as:
240
-
241
-* If the blueprint proposes a change to the driver API, discussion of how
242
-  other hypervisors would implement the feature is required.
243
-
244
-
245
-Implementation
246
-==============
247
-
248
-Assignee(s)
249
------------
250
-
251
-Who is leading the writing of the code? Or is this a blueprint where you're
252
-throwing it out there to see who picks it up?
253
-
254
-If more than one person is working on the implementation, please designate the
255
-primary author and contact.
256
-
257
-Primary assignee:
258
-  <launchpad-id or None>
259
-
260
-Other contributors:
261
-  <launchpad-id or None>
262
-
263
-Work Items
264
-----------
265
-
266
-Work items or tasks -- break the feature up into the things that need to be
267
-done to implement it. Those parts might end up being done by different people,
268
-but we're mostly trying to understand the timeline for implementation.
269
-
270
-
271
-Dependencies
272
-============
273
-
274
-* Include specific references to specs and/or blueprints in openstack-chef, or in other
275
-  projects, that this one either depends on or is related to.
276
-
277
-* If this requires functionality of another project that is not currently used
278
-  by openstack-chef (such as the glance v2 API when we previously only required v1),
279
-  document that fact.
280
-
281
-* Does this feature require any new library dependencies or code otherwise not
282
-  included in OpenStack? Or does it depend on a specific version of library?
283
-
284
-
285
-Testing
286
-=======
287
-
288
-Please discuss how the change will be tested. We especially want to know what
289
-tempest tests will be added. It is assumed that unit test coverage will be
290
-added so that doesn't need to be mentioned explicitly, but discussion of why
291
-you think unit tests are sufficient and we don't need to add more tempest
292
-tests would need to be included.
293
-
294
-Is this untestable in gate given current limitations (specific hardware /
295
-software configurations available)? If so, are there mitigation plans (3rd
296
-party testing, gate enhancements, etc).
297
-
298
-
299
-Documentation Impact
300
-====================
301
-
302
-What is the impact on the docs team of this change? Some changes might require
303
-donating resources to the docs team to have the documentation updated. Don't
304
-repeat details discussed above, but please reference them here.
305
-
306
-
307
-References
308
-==========
309
-
310
-Please add any useful references here. You are not required to have any
311
-reference. Moreover, this specification should still make sense when your
312
-references are unavailable. Examples of what you could include are:
313
-
314
-* Links to mailing list or IRC discussions
315
-
316
-* Links to notes from a summit session
317
-
318
-* Links to relevant research, if appropriate
319
-
320
-* Related specifications as appropriate (e.g. if it's an EC2 thing, link the
321
-  EC2 docs)
322
-
323
-* Anything else you feel it is worthwhile to refer to

+ 200
- 0
specs/juno/common/cookbook-versioning.rst View File

@@ -0,0 +1,200 @@
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
+Openstack Cookbook Versioning scheme
9
+==========================================
10
+
11
+Include the URL of your launchpad blueprint:
12
+
13
+https://blueprints.launchpad.net/openstack-chef/+spec/example
14
+
15
+There has been multiple threads on the way that cookbook versioning is done.
16
+This doc is to attempt to consolidate and organize and ideally agree upon some
17
+guidelines on the way to bump/change work on the versioning for
18
+`the cookbooks <https://github.com/stackforge/cookbook-openstack-common>`_ for
19
+instance the common cookbook.
20
+
21
+Problem description
22
+===================
23
+
24
+There is no standardization on the cookbook versioning we have. This doc is the
25
+attempt to give some general guidelines to fix this.
26
+
27
+
28
+Proposed change
29
+===============
30
+
31
+General Guidelines
32
+------------------
33
+
34
+When submitting cookbook patches, it is generally required that the version
35
+number (within metadata.rb) is incremented in a manor reflective of the level
36
+of the change.  Any patch should also update the CHANGELOG.md and if appropriate
37
+the README.md should reflect the changes and any relevant how-to instructions. The
38
+CHANGELOG.md is our executive summary of changes, it should inform what the change
39
+was in a quick manner.
40
+
41
+There are some differences between the development of patches on the Master and
42
+Stable branches.  There is more restrictive and vigorous oversight given to changes
43
+on the Stable branches.  The Master branch is bleeding edge and can relax the
44
+version requirement in some simple cases to allow for increased productivity.
45
+
46
+Semantic Versioning
47
+-------------------
48
+
49
+The cookbooks use the Semantic Versioning system (see http://semver.org)
50
+The system uses a three part version number, Major.Minor.Patch.
51
+For example: 9.2.33
52
+
53
+The Major number shouldn't change within a development branch. It will reflect the
54
+number that is the Alphabetized Letter of the base Openstack release,
55
+see: https://wiki.openstack.org/wiki/Releases.  An example would be Icehouse
56
+being the 9th letter and the 9th release all the stable cookbooks would be 9.Y.Z.
57
+When the Master branch becomes stabilized, a new Stable branch will be created from
58
+it and the Major number in the Master will be incremented by the core team.
59
+
60
+The Minor and Patch numbers will be incremented as described in the branch specific
61
+sections below.
62
+
63
+Stable Branch
64
+-------------
65
+
66
+The Stable branch cookbooks must leverage the Semantic Versioning system exclusively.
67
+All patches must update the metadata.rb and the CHANGELOG.md at a minimum.
68
+All patches should try to be backwards compatible.
69
+
70
++-------------------------------------------------------------------------+-----------------+
71
+| Stable Branch Example Situations                                        | Level of Change |
72
++=========================================================================+=================+
73
+| add a recipe                                                            | Increment Minor |
74
++-------------------------------------------------------------------------+-----------------+
75
+| add a function or method                                                | Increment Minor |
76
++-------------------------------------------------------------------------+-----------------+
77
+| change Gemfile or Berksfile                                             | Increment Minor |
78
++-------------------------------------------------------------------------+-----------------+
79
+| backport a fix from Master branch                                       | Increment Minor |
80
++-------------------------------------------------------------------------+-----------------+
81
+| add attribute for a value in a configuration file with the same default | Increment Patch |
82
++-------------------------------------------------------------------------+-----------------+
83
+| changing a resource option                                              | Increment Patch |
84
++-------------------------------------------------------------------------+-----------------+
85
+| add a test                                                              | Increment Patch |
86
++-------------------------------------------------------------------------+-----------------+
87
+| fix a broken recipe                                                     | Increment Patch |
88
++-------------------------------------------------------------------------+-----------------+
89
+| re-factoring recipe or test                                             | Increment Patch |
90
++-------------------------------------------------------------------------+-----------------+
91
+
92
+The table above shows some examples of different levels of changes introduced by a patch and
93
+what part of the version number to increment for Stable branches.
94
+
95
+Version Locking
96
+^^^^^^^^^^^^^^^
97
+
98
+The Stable branches are also locked down by added Berksfile.lock and Gemfile.lock to each
99
+cookbook.  If any changes are made to the Gemfile, the Gemfile.lock would also have to be
100
+updated.  If any changes are dependent upon other cookbook changes, then the Berkfile.lock
101
+and metadata.rb files would need to be updated accordingly.
102
+
103
+Cookbook Dependencies
104
+^^^^^^^^^^^^^^^^^^^^^
105
+
106
+When a change requires hits to multiple cookbooks, like when adding attributes to Common, the
107
+metadata.rb file would need to be updated to reflect that required version level.  The
108
+Berksfile.lock would also need to be updated with the commit id of the dependent change.
109
+
110
+Master Branch
111
+-------------
112
+
113
+The master cookbook should leverage the Semantic Versioning system lightly.
114
+We consider the master branch a fast paced "Work in Progress" until we come to the Release
115
+Candidate 1 date (RC-1). This means it will be under rapid and active development where
116
+versioning isn't always required.
117
+All patches must update the the CHANGELOG.md at a minimum.
118
+
119
++-------------------------------------------------------------------------+------------------+
120
+| Master Branch Example Situations                                        | Level of Change  |
121
++=========================================================================+==================+
122
+| Branching for a new Stable branch                                       | Increment Major  |
123
++-------------------------------------------------------------------------+------------------+
124
+| add a recipe                                                            | Increment Minor  |
125
++-------------------------------------------------------------------------+------------------+
126
+| add a function or method                                                | Increment Minor  |
127
++-------------------------------------------------------------------------+------------------+
128
+| change Gemfile or Berksfile                                             | Increment Minor  |
129
++-------------------------------------------------------------------------+------------------+
130
+| add attribute for a value in a configuration file with the same default | Increment Patch**|
131
++-------------------------------------------------------------------------+------------------+
132
+| changing a resource option                                              | Increment Patch**|
133
++-------------------------------------------------------------------------+------------------+
134
+| add a test                                                              | Increment Patch**|
135
++-------------------------------------------------------------------------+------------------+
136
+| fix a broken recipe                                                     | Increment Patch**|
137
++-------------------------------------------------------------------------+------------------+
138
+| re-factoring recipe or test                                             | Increment Patch**|
139
++-------------------------------------------------------------------------+------------------+
140
+
141
+The table above shows some examples of different levels of changes introduced by a patch and
142
+what part of the version number to increment for Master branches.
143
+
144
+** There are cases where incrementing the Patch number is not necessary and only updating the
145
+CHANGELOG.md is required.  To avoid re-base collisions on Patch number changes and allow more
146
+rapid development, if the change falls within these guidelines, incrementing the Patch version
147
+would not be required.
148
+- When the change only effects a single cookbook
149
+- When the change is just a simple addition of a new attribute for a template and no other
150
+logic change is required
151
+- When a patch only effects the tests
152
+- When a patch only effect the README or other comments
153
+
154
+Version Locking
155
+^^^^^^^^^^^^^^^
156
+
157
+The Master branch is NOT locked down a Berksfile.lock or Gemfile.lock.  Changes to the Berksfile
158
+and Gemfile can be made directly.
159
+
160
+Cookbook Dependencies
161
+^^^^^^^^^^^^^^^^^^^^^
162
+
163
+When a change requires hits to multiple cookbooks, like when adding attributes to Common, the
164
+metadata.rb file would need to be updated to reflect that required version level.
165
+
166
+
167
+Implementation
168
+==============
169
+
170
+Assignee(s)
171
+-----------
172
+
173
+Everyone because this is an over arching process ;)
174
+
175
+Work Items
176
+----------
177
+
178
+None.
179
+
180
+
181
+Dependencies
182
+============
183
+
184
+None, apart from the community approving these guide lines.
185
+
186
+Testing
187
+=======
188
+
189
+None.
190
+
191
+Documentation Impact
192
+====================
193
+
194
+See above, this should also be put on the wiki too.
195
+
196
+References
197
+==========
198
+
199
+This `youtube video <http://youtu.be/jA9L_g-d-X4>`_ is the major discussion
200
+about this topic. There has also been multiple comments on the google group.

+ 0
- 323
specs/juno/template.rst View File

@@ -1,323 +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/openstack-chef/+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 using this template:
21
-
22
-* Your spec should be in ReSTructured text, like this template.
23
-
24
-* Please wrap text at 79 columns.
25
-
26
-* The filename in the git repository should match the launchpad URL, for
27
-  example a URL of: https://blueprints.launchpad.net/openstack-chef/+spec/awesome-thing
28
-  should be named awesome-thing.rst
29
-
30
-* Please do not delete any of the sections in this template.  If you have
31
-  nothing to say for a whole section, just write: None
32
-
33
-* For help with syntax, see http://sphinx-doc.org/rest.html
34
-
35
-* To test out your formatting, build the docs using tox and see the generated
36
-  HTML file in doc/build/html/specs/<path_of_your_file>
37
-
38
-* If you would like to provide a diagram with your spec, ascii diagrams are
39
-  required.  http://asciiflow.com/ is a very nice tool to assist with making
40
-  ascii diagrams.  The reason for this is that the tool used to review specs is
41
-  based purely on plain text.  Plain text will allow review to proceed without
42
-  having to look at additional files which can not be viewed in gerrit.  It
43
-  will also allow inline feedback on the diagram itself.
44
-
45
-Problem description
46
-===================
47
-
48
-A detailed description of the problem:
49
-
50
-* For a new feature this might be use cases. Ensure you are clear about the
51
-  actors in each use case: End User vs Deployer
52
-
53
-* For a major reworking of something existing it would describe the
54
-  problems in that feature that are being addressed.
55
-
56
-
57
-Proposed change
58
-===============
59
-
60
-Here is where you cover the change you propose to make in detail. How do you
61
-propose to solve this problem?
62
-
63
-If this is one part of a larger effort make it clear where this piece ends. In
64
-other words, what's the scope of this effort?
65
-
66
-Alternatives
67
-------------
68
-
69
-What other ways could we do this thing? Why aren't we using those? This doesn't
70
-have to be a full literature review, but it should demonstrate that thought has
71
-been put into why the proposed solution is an appropriate one.
72
-
73
-Data model impact
74
------------------
75
-
76
-Changes which require modifications to the data model often have a wider impact
77
-on the system.  The community often has strong opinions on how the data model
78
-should be evolved, from both a functional and performance perspective. It is
79
-therefore important to capture and gain agreement as early as possible on any
80
-proposed changes to the data model.
81
-
82
-Questions which need to be addressed by this section include:
83
-
84
-* What new data objects and/or database schema changes is this going to
85
-  require?
86
-
87
-* What database migrations will accompany this change.
88
-
89
-* How will the initial set of new data objects be generated, for example if you
90
-  need to take into account existing instances, or modify other existing data
91
-  describe how that will work.
92
-
93
-REST API impact
94
----------------
95
-
96
-Each API method which is either added or changed should have the following
97
-
98
-* Specification for the method
99
-
100
-  * A description of what the method does suitable for use in
101
-    user documentation
102
-
103
-  * Method type (POST/PUT/GET/DELETE)
104
-
105
-  * Normal http response code(s)
106
-
107
-  * Expected error http response code(s)
108
-
109
-    * A description for each possible error code should be included
110
-      describing semantic errors which can cause it such as
111
-      inconsistent parameters supplied to the method, or when an
112
-      instance is not in an appropriate state for the request to
113
-      succeed. Errors caused by syntactic problems covered by the JSON
114
-      schema defintion do not need to be included.
115
-
116
-  * URL for the resource
117
-
118
-  * Parameters which can be passed via the url
119
-
120
-  * JSON schema definition for the body data if allowed
121
-
122
-  * JSON schema definition for the response data if any
123
-
124
-* Example use case including typical API samples for both data supplied
125
-  by the caller and the response
126
-
127
-* Discuss any policy changes, and discuss what things a deployer needs to
128
-  think about when defining their policy.
129
-
130
-Example JSON schema definitions can be found in the openstack-chef tree
131
-http://git.openstack.org/cgit/openstack/openstack-chef/tree/openstack-chef/api/openstack/compute/schemas/v3
132
-
133
-Note that the schema should be defined as restrictively as
134
-possible. Parameters which are required should be marked as such and
135
-only under exceptional circumstances should additional parameters
136
-which are not defined in the schema be permitted (eg
137
-additionaProperties should be False).
138
-
139
-Reuse of existing predefined parameter types such as regexps for
140
-passwords and user defined names is highly encouraged.
141
-
142
-Security impact
143
----------------
144
-
145
-Describe any potential security impact on the system.  Some of the items to
146
-consider include:
147
-
148
-* Does this change touch sensitive data such as tokens, keys, or user data?
149
-
150
-* Does this change alter the API in a way that may impact security, such as
151
-  a new way to access sensitive information or a new way to login?
152
-
153
-* Does this change involve cryptography or hashing?
154
-
155
-* Does this change require the use of sudo or any elevated privileges?
156
-
157
-* Does this change involve using or parsing user-provided data? This could
158
-  be directly at the API level or indirectly such as changes to a cache layer.
159
-
160
-* Can this change enable a resource exhaustion attack, such as allowing a
161
-  single API interaction to consume significant server resources? Some examples
162
-  of this include launching subprocesses for each connection, or entity
163
-  expansion attacks in XML.
164
-
165
-For more detailed guidance, please see the OpenStack Security Guidelines as
166
-a reference (https://wiki.openstack.org/wiki/Security/Guidelines).  These
167
-guidelines are a work in progress and are designed to help you identify
168
-security best practices.  For further information, feel free to reach out
169
-to the OpenStack Security Group at openstack-security@lists.openstack.org.
170
-
171
-Notifications impact
172
---------------------
173
-
174
-Please specify any changes to notifications. Be that an extra notification,
175
-changes to an existing notification, or removing a notification.
176
-
177
-Other end user impact
178
----------------------
179
-
180
-Aside from the API, are there other ways a user will interact with this
181
-feature?
182
-
183
-* Does this change have an impact on python-openstack-chefclient? What does the user
184
-  interface there look like?
185
-
186
-Performance Impact
187
-------------------
188
-
189
-Describe any potential performance impact on the system, for example
190
-how often will new code be called, and is there a major change to the calling
191
-pattern of existing code.
192
-
193
-Examples of things to consider here include:
194
-
195
-* A periodic task might look like a small addition but if it calls conductor or
196
-  another service the load is multiplied by the number of nodes in the system.
197
-
198
-* Scheduler filters get called once per host for every instance being created,
199
-  so any latency they introduce is linear with the size of the system.
200
-
201
-* A small change in a utility function or a commonly used decorator can have a
202
-  large impacts on performance.
203
-
204
-* Calls which result in a database queries (whether direct or via conductor)
205
-  can have a profound impact on performance when called in critical sections of
206
-  the code.
207
-
208
-* Will the change include any locking, and if so what considerations are there
209
-  on holding the lock?
210
-
211
-Other deployer impact
212
----------------------
213
-
214
-Discuss things that will affect how you deploy and configure OpenStack
215
-that have not already been mentioned, such as:
216
-
217
-* What config options are being added? Should they be more generic than
218
-  proposed (for example a flag that other hypervisor drivers might want to
219
-  implement as well)? Are the default values ones which will work well in
220
-  real deployments?
221
-
222
-* Is this a change that takes immediate effect after its merged, or is it
223
-  something that has to be explicitly enabled?
224
-
225
-* If this change is a new binary, how would it be deployed?
226
-
227
-* Please state anything that those doing continuous deployment, or those
228
-  upgrading from the previous release, need to be aware of. Also describe
229
-  any plans to deprecate configuration values or features.  For example, if we
230
-  change the directory name that instances are stored in, how do we handle
231
-  instance directories created before the change landed?  Do we move them?  Do
232
-  we have a special case in the code? Do we assume that the operator will
233
-  recreate all the instances in their cloud?
234
-
235
-Developer impact
236
-----------------
237
-
238
-Discuss things that will affect other developers working on OpenStack,
239
-such as:
240
-
241
-* If the blueprint proposes a change to the driver API, discussion of how
242
-  other hypervisors would implement the feature is required.
243
-
244
-
245
-Implementation
246
-==============
247
-
248
-Assignee(s)
249
------------
250
-
251
-Who is leading the writing of the code? Or is this a blueprint where you're
252
-throwing it out there to see who picks it up?
253
-
254
-If more than one person is working on the implementation, please designate the
255
-primary author and contact.
256
-
257
-Primary assignee:
258
-  <launchpad-id or None>
259
-
260
-Other contributors:
261
-  <launchpad-id or None>
262
-
263
-Work Items
264
-----------
265
-
266
-Work items or tasks -- break the feature up into the things that need to be
267
-done to implement it. Those parts might end up being done by different people,
268
-but we're mostly trying to understand the timeline for implementation.
269
-
270
-
271
-Dependencies
272
-============
273
-
274
-* Include specific references to specs and/or blueprints in openstack-chef, or in other
275
-  projects, that this one either depends on or is related to.
276
-
277
-* If this requires functionality of another project that is not currently used
278
-  by openstack-chef (such as the glance v2 API when we previously only required v1),
279
-  document that fact.
280
-
281
-* Does this feature require any new library dependencies or code otherwise not
282
-  included in OpenStack? Or does it depend on a specific version of library?
283
-
284
-
285
-Testing
286
-=======
287
-
288
-Please discuss how the change will be tested. We especially want to know what
289
-tempest tests will be added. It is assumed that unit test coverage will be
290
-added so that doesn't need to be mentioned explicitly, but discussion of why
291
-you think unit tests are sufficient and we don't need to add more tempest
292
-tests would need to be included.
293
-
294
-Is this untestable in gate given current limitations (specific hardware /
295
-software configurations available)? If so, are there mitigation plans (3rd
296
-party testing, gate enhancements, etc).
297
-
298
-
299
-Documentation Impact
300
-====================
301
-
302
-What is the impact on the docs team of this change? Some changes might require
303
-donating resources to the docs team to have the documentation updated. Don't
304
-repeat details discussed above, but please reference them here.
305
-
306
-
307
-References
308
-==========
309
-
310
-Please add any useful references here. You are not required to have any
311
-reference. Moreover, this specification should still make sense when your
312
-references are unavailable. Examples of what you could include are:
313
-
314
-* Links to mailing list or IRC discussions
315
-
316
-* Links to notes from a summit session
317
-
318
-* Links to relevant research, if appropriate
319
-
320
-* Related specifications as appropriate (e.g. if it's an EC2 thing, link the
321
-  EC2 docs)
322
-
323
-* Anything else you feel it is worthwhile to refer to

Loading…
Cancel
Save