summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJenkins <jenkins@review.openstack.org>2017-06-17 10:11:01 +0000
committerGerrit Code Review <review@openstack.org>2017-06-17 10:11:01 +0000
commitab0dba40d15aa9c003af9e25a2ef134355421421 (patch)
tree40f8b305c93a2c8cbd5293772790092d38920c5d
parentbaa4ac9151722d053051f083da48fc815f71e491 (diff)
parenteee9d2ca8019623a6ab3700a86d01587f6e8db1c (diff)
Merge "docs: Fix indent level"
-rw-r--r--TESTING.rst34
-rw-r--r--doc/source/stadium/governance.rst308
2 files changed, 170 insertions, 172 deletions
diff --git a/TESTING.rst b/TESTING.rst
index 70a1d67..761ea39 100644
--- a/TESTING.rst
+++ b/TESTING.rst
@@ -50,17 +50,17 @@ We will talk about three classes of tests: unit, functional and integration.
50Each respective category typically targets a larger scope of code. Other than 50Each respective category typically targets a larger scope of code. Other than
51that broad categorization, here are a few more characteristic: 51that broad categorization, here are a few more characteristic:
52 52
53 * Unit tests - Should be able to run on your laptop, directly following a 53* Unit tests - Should be able to run on your laptop, directly following a
54 'git clone' of the project. The underlying system must not be mutated, 54 'git clone' of the project. The underlying system must not be mutated,
55 mocks can be used to achieve this. A unit test typically targets a function 55 mocks can be used to achieve this. A unit test typically targets a function
56 or class. 56 or class.
57 * Functional tests - Run against a pre-configured environment 57* Functional tests - Run against a pre-configured environment
58 (tools/configure_for_func_testing.sh). Typically test a component 58 (tools/configure_for_func_testing.sh). Typically test a component
59 such as an agent using no mocks. 59 such as an agent using no mocks.
60 * Integration tests - Run against a running cloud, often target the API level, 60* Integration tests - Run against a running cloud, often target the API level,
61 but also 'scenarios' or 'user stories'. You may find such tests under 61 but also 'scenarios' or 'user stories'. You may find such tests under
62 tests/tempest/api, tests/tempest/scenario, tests/fullstack, and in the 62 tests/tempest/api, tests/tempest/scenario, tests/fullstack, and in the
63 Tempest and Rally projects. 63 Tempest and Rally projects.
64 64
65Tests in the Neutron tree are typically organized by the testing infrastructure 65Tests in the Neutron tree are typically organized by the testing infrastructure
66used, and not by the scope of the test. For example, many tests under the 66used, and not by the scope of the test. For example, many tests under the
@@ -469,9 +469,7 @@ the tracking of long-running tests and other things.
469 469
470For more information on the standard Tox-based test infrastructure used by 470For more information on the standard Tox-based test infrastructure used by
471OpenStack and how to do some common test/debugging procedures with Testr, 471OpenStack and how to do some common test/debugging procedures with Testr,
472see this wiki page: 472see this wiki page: https://wiki.openstack.org/wiki/Testr
473
474 https://wiki.openstack.org/wiki/Testr
475 473
476.. _Testr: https://wiki.openstack.org/wiki/Testr 474.. _Testr: https://wiki.openstack.org/wiki/Testr
477.. _tox: http://tox.readthedocs.org/en/latest/ 475.. _tox: http://tox.readthedocs.org/en/latest/
@@ -593,10 +591,10 @@ doc/source/devref/testing_coverage.rst. You could also rely on Zuul
593logs, that are generated post-merge (not every project builds coverage 591logs, that are generated post-merge (not every project builds coverage
594results). To access them, do the following: 592results). To access them, do the following:
595 593
596 * Check out the latest `merge commit <https://review.openstack.org/gitweb?p=openstack/neutron.git;a=search;s=Jenkins;st=author>`_ 594* Check out the latest `merge commit <https://review.openstack.org/gitweb?p=openstack/neutron.git;a=search;s=Jenkins;st=author>`_
597 * Go to: http://logs.openstack.org/<first-2-digits-of-sha1>/<sha1>/post/neutron-coverage/. 595* Go to: http://logs.openstack.org/<first-2-digits-of-sha1>/<sha1>/post/neutron-coverage/.
598 * `Spec <https://review.openstack.org/#/c/221494/>`_ is a work in progress to 596* `Spec <https://review.openstack.org/#/c/221494/>`_ is a work in progress to
599 provide a better landing page. 597 provide a better landing page.
600 598
601Debugging 599Debugging
602--------- 600---------
diff --git a/doc/source/stadium/governance.rst b/doc/source/stadium/governance.rst
index 2760c49..e6d8dc6 100644
--- a/doc/source/stadium/governance.rst
+++ b/doc/source/stadium/governance.rst
@@ -77,68 +77,68 @@ This means showing proof of adoption of practices as led by the Neutron core
77team. Some of these practices are typically already followed by the most 77team. Some of these practices are typically already followed by the most
78mature OpenStack projects: 78mature OpenStack projects:
79 79
80 * Exhaustive documentation: it is expected that each project will have a 80* Exhaustive documentation: it is expected that each project will have a
81 `developer <http://docs.openstack.org/developer/neutron/>`_, 81 `developer <http://docs.openstack.org/developer/neutron/>`_,
82 `user/operator <http://docs.openstack.org/mitaka/networking-guide/>`_ 82 `user/operator <http://docs.openstack.org/mitaka/networking-guide/>`_
83 and `API <http://developer.openstack.org/api-ref/networking/>`_ 83 and `API <http://developer.openstack.org/api-ref/networking/>`_
84 documentations available. 84 documentations available.
85 85
86 * Exhaustive OpenStack CI coverage: unit, functional, and tempest coverage 86* Exhaustive OpenStack CI coverage: unit, functional, and tempest coverage
87 using OpenStack CI (upstream) resources so that `Grafana <http://grafana.openstack.org/dashboard/db/neutron-failure-rate>`_ 87 using OpenStack CI (upstream) resources so that `Grafana <http://grafana.openstack.org/dashboard/db/neutron-failure-rate>`_
88 and `OpenStack Health <http://status.openstack.org/openstack-health/#/>`_ 88 and `OpenStack Health <http://status.openstack.org/openstack-health/#/>`_
89 support is available. Access to CI resources and historical data by the 89 support is available. Access to CI resources and historical data by the
90 team is key to ensuring stability and robustness of a project. 90 team is key to ensuring stability and robustness of a project.
91 In particular, it is of paramount importance to ensure that DB models/migrations 91 In particular, it is of paramount importance to ensure that DB models/migrations
92 are tested functionally to prevent data inconsistency issues or unexpected 92 are tested functionally to prevent data inconsistency issues or unexpected
93 DB logic errors due to schema/models mismatch. For more details, please 93 DB logic errors due to schema/models mismatch. For more details, please
94 look at the following resources: 94 look at the following resources:
95 95
96 * https://review.openstack.org/#/c/346091/ 96 * https://review.openstack.org/#/c/346091/
97 * https://review.openstack.org/#/c/346272/ 97 * https://review.openstack.org/#/c/346272/
98 * https://review.openstack.org/#/c/346083/ 98 * https://review.openstack.org/#/c/346083/
99 99
100 More Database related information can be found on: 100 More Database related information can be found on:
101 101
102 * http://docs.openstack.org/developer/neutron/devref/alembic_migrations.html 102 * http://docs.openstack.org/developer/neutron/devref/alembic_migrations.html
103 * http://docs.openstack.org/developer/neutron/devref/db_layer.html 103 * http://docs.openstack.org/developer/neutron/devref/db_layer.html
104 104
105 Bear in mind that many projects have been transitioning their codebase and 105 Bear in mind that many projects have been transitioning their codebase and
106 tests to fully support Python 3+, and it is important that each Stadium 106 tests to fully support Python 3+, and it is important that each Stadium
107 project supports Python 3+ the same way Neutron core does. For more 107 project supports Python 3+ the same way Neutron core does. For more
108 information on how to do testing, please refer to the 108 information on how to do testing, please refer to the
109 `Neutron testing documentation <http://docs.openstack.org/developer/neutron/devref/development.environment.html#testing-neutron>`_. 109 `Neutron testing documentation <http://docs.openstack.org/developer/neutron/devref/development.environment.html#testing-neutron>`_.
110 110
111 * Good release footprint, according to the chosen `release model <http://governance.openstack.org/reference/tags/#release-management-tags>`_. 111* Good release footprint, according to the chosen `release model <http://governance.openstack.org/reference/tags/#release-management-tags>`_.
112 112
113 * Adherence to deprecation and `stable backports policies <http://governance.openstack.org/reference/tags/#stable-maintenance-tags>`_. 113* Adherence to deprecation and `stable backports policies <http://governance.openstack.org/reference/tags/#stable-maintenance-tags>`_.
114 114
115 * Demonstrated ability to do `upgrades <http://governance.openstack.org/reference/tags/assert_supports-upgrade.html>`_ 115* Demonstrated ability to do `upgrades <http://governance.openstack.org/reference/tags/assert_supports-upgrade.html>`_
116 and/or `rolling upgrades <http://governance.openstack.org/reference/tags/assert_supports-rolling-upgrade.html>`_, 116 and/or `rolling upgrades <http://governance.openstack.org/reference/tags/assert_supports-rolling-upgrade.html>`_,
117 where applicable. This means having grenade support on top of the CI 117 where applicable. This means having grenade support on top of the CI
118 coverage as described above. 118 coverage as described above.
119 119
120 * Client bindings and CLI developed according to the OpenStack Client `plugin model <http://docs.openstack.org/developer/python-openstackclient/plugins.html>`_. 120* Client bindings and CLI developed according to the OpenStack Client `plugin model <http://docs.openstack.org/developer/python-openstackclient/plugins.html>`_.
121 121
122On top of the above mentioned criteria, the following also are taken into 122On top of the above mentioned criteria, the following also are taken into
123consideration: 123consideration:
124 124
125 * A project must use, adopt and implement open software and technologies. 125* A project must use, adopt and implement open software and technologies.
126 126
127 * A project must integrate with Neutron via one of the supported, advertised 127* A project must integrate with Neutron via one of the supported, advertised
128 and maintained public Python APIs. REST API does not qualify (the project 128 and maintained public Python APIs. REST API does not qualify (the project
129 python-neutronclient is an exception). 129 python-neutronclient is an exception).
130 130
131 * It adopts neutron-lib (with related hacking rules applied), and has proof 131* It adopts neutron-lib (with related hacking rules applied), and has proof
132 of good decoupling from Neutron core internals. 132 of good decoupling from Neutron core internals.
133 133
134 * It provides an API that adopts API guidelines as set by the Neutron core 134* It provides an API that adopts API guidelines as set by the Neutron core
135 team, and that relies on an open implementation. 135 team, and that relies on an open implementation.
136 136
137 * It adopts modular interfaces to provide networking services: this means 137* It adopts modular interfaces to provide networking services: this means
138 that L2/7 services are provided in the form of ML2 mech drivers and 138 that L2/7 services are provided in the form of ML2 mech drivers and
139 service plugins respectively. A service plugin can expose a driver 139 service plugins respectively. A service plugin can expose a driver
140 interface to support multiple backend technologies, and/or adopt the 140 interface to support multiple backend technologies, and/or adopt the
141 flavor framework as necessary. 141 flavor framework as necessary.
142 142
143Adding or removing projects to the Stadium 143Adding or removing projects to the Stadium
144------------------------------------------ 144------------------------------------------
@@ -179,112 +179,112 @@ enhancements.
179Checklist 179Checklist
180--------- 180---------
181 181
182 * How to integrate documentation into docs.o.o: The documentation 182* How to integrate documentation into docs.o.o: The documentation
183 website has a section for `project developer documentation <http://docs.openstack.org/developer/openstack-projects.html>`_. 183 website has a section for `project developer documentation <http://docs.openstack.org/developer/openstack-projects.html>`_.
184 Each project in the Neutron Stadium must have an entry under the 184 Each project in the Neutron Stadium must have an entry under the
185 'Networking Sub Projects' section that points to the developer 185 'Networking Sub Projects' section that points to the developer
186 documentation for the project, available at http://docs.openstack.org/developer/<your-project>/. 186 documentation for the project, available at http://docs.openstack.org/developer/<your-project>/.
187 This is a two step process that involves the following: 187 This is a two step process that involves the following:
188 188
189 * Build the artefacts: this can be done by following example 189 * Build the artefacts: this can be done by following example
190 https://review.openstack.org/#/c/293399/. 190 https://review.openstack.org/#/c/293399/.
191 * Publish the artefacts: this can be done by following example 191 * Publish the artefacts: this can be done by following example
192 https://review.openstack.org/#/c/216448/. 192 https://review.openstack.org/#/c/216448/.
193 193
194 More information can also be found on the 194 More information can also be found on the
195 `project creator guide <http://docs.openstack.org/infra/manual/creators.html#add-link-to-your-developer-documentation>`_. 195 `project creator guide <http://docs.openstack.org/infra/manual/creators.html#add-link-to-your-developer-documentation>`_.
196 196
197 * How to integrate into Grafana: Grafana is a great tool that provides 197* How to integrate into Grafana: Grafana is a great tool that provides
198 the ability to display historical series, like failure rates of 198 the ability to display historical series, like failure rates of
199 OpenStack CI jobs. A few examples that added dashboards over time are: 199 OpenStack CI jobs. A few examples that added dashboards over time are:
200 200
201 * `Neutron <https://review.openstack.org/#/c/278832/>`_. 201 * `Neutron <https://review.openstack.org/#/c/278832/>`_.
202 * `Networking-OVN <https://review.openstack.org/#/c/335791>`_. 202 * `Networking-OVN <https://review.openstack.org/#/c/335791>`_.
203 * `Networking-Midonet <https://review.openstack.org/#/c/315033>`_. 203 * `Networking-Midonet <https://review.openstack.org/#/c/315033>`_.
204 204
205 Any subproject must have a Grafana dashboard that shows failure 205 Any subproject must have a Grafana dashboard that shows failure
206 rates for at least Gate and Check queues. 206 rates for at least Gate and Check queues.
207 207
208 * How to integrate into neutron-lib's CI: there are a number of steps 208* How to integrate into neutron-lib's CI: there are a number of steps
209 required to integrate with neutron-lib CI and adopt neutron-lib in 209 required to integrate with neutron-lib CI and adopt neutron-lib in
210 general. One step is to validate that neutron-lib master is working 210 general. One step is to validate that neutron-lib master is working
211 with the master of a given project that uses neutron-lib. For example 211 with the master of a given project that uses neutron-lib. For example
212 `patch <https://review.openstack.org/#/c/338603/>`_ introduced such 212 `patch <https://review.openstack.org/#/c/338603/>`_ introduced such
213 support for the Neutron project. Any subproject that wants to do the 213 support for the Neutron project. Any subproject that wants to do the
214 same would need to adopt the following few lines: 214 same would need to adopt the following few lines:
215 215
216 #. https://review.openstack.org/#/c/338603/4/jenkins/jobs/projects.yaml@4685 216 #. https://review.openstack.org/#/c/338603/4/jenkins/jobs/projects.yaml@4685
217 #. https://review.openstack.org/#/c/338603/3/zuul/layout.yaml@8501 217 #. https://review.openstack.org/#/c/338603/3/zuul/layout.yaml@8501
218 #. https://review.openstack.org/#/c/338603/4/grafana/neutron.yaml@39 218 #. https://review.openstack.org/#/c/338603/4/grafana/neutron.yaml@39
219 219
220 Line 1 and 2 respectively add a job to the periodic queue for the 220 Line 1 and 2 respectively add a job to the periodic queue for the
221 project, whereas line 3 introduced the failure rate trend for the 221 project, whereas line 3 introduced the failure rate trend for the
222 periodic job to spot failure spikes etc. Make sure your project has 222 periodic job to spot failure spikes etc. Make sure your project has
223 the following: 223 the following:
224 224
225 #. https://review.openstack.org/#/c/357086/ 225 #. https://review.openstack.org/#/c/357086/
226 #. https://review.openstack.org/#/c/359143/ 226 #. https://review.openstack.org/#/c/359143/
227 227
228 * How to port api-ref over to neutron-lib: to publish the subproject 228* How to port api-ref over to neutron-lib: to publish the subproject
229 API reference into the `Networking API guide <http://developer.openstack.org/api-ref/networking/>`_ 229 API reference into the `Networking API guide <http://developer.openstack.org/api-ref/networking/>`_
230 you must contribute the API documentation into neutron-lib's api-ref 230 you must contribute the API documentation into neutron-lib's api-ref
231 directory as done in the `WADL/REST transition patch <https://review.openstack.org/#/c/327510/>`_. 231 directory as done in the `WADL/REST transition patch <https://review.openstack.org/#/c/327510/>`_.
232 Once this is done successfully, a link to the subproject API will 232 Once this is done successfully, a link to the subproject API will
233 show under the published `table of content <https://github.com/openstack/neutron-lib/blob/master/api-ref/source/index.rst>`_. 233 show under the published `table of content <https://github.com/openstack/neutron-lib/blob/master/api-ref/source/index.rst>`_.
234 An RFE bug tracking this effort effectively initiates the request 234 An RFE bug tracking this effort effectively initiates the request
235 for Stadium inclusion, where all the aspects as outlined in this 235 for Stadium inclusion, where all the aspects as outlined in this
236 documented are reviewed by the PTL. 236 documented are reviewed by the PTL.
237 237
238 * How to port API definitions over the neutron-lib: the most basic 238* How to port API definitions over the neutron-lib: the most basic
239 steps to port API definitions over to neutron-lib are demonstrated 239 steps to port API definitions over to neutron-lib are demonstrated
240 in the following patches: 240 in the following patches:
241 241
242 * https://review.openstack.org/#/c/353131/ 242 * https://review.openstack.org/#/c/353131/
243 * https://review.openstack.org/#/c/353132/ 243 * https://review.openstack.org/#/c/353132/
244 244
245 The `neutron-lib patch <https://review.openstack.org/#/c/353131/>`_ 245 The `neutron-lib patch <https://review.openstack.org/#/c/353131/>`_
246 introduces the elements that define the API, and testing coverage 246 introduces the elements that define the API, and testing coverage
247 validates that the resource and actions maps use valid keywords. 247 validates that the resource and actions maps use valid keywords.
248 API reference documentation is provided alongside the definition to 248 API reference documentation is provided alongside the definition to
249 keep everything in one place. 249 keep everything in one place.
250 The `neutron patch <https://review.openstack.org/#/c/353132/>`_ 250 The `neutron patch <https://review.openstack.org/#/c/353132/>`_
251 uses the Neutron extension framework to plug the API definition 251 uses the Neutron extension framework to plug the API definition
252 on top of the Neutron API backbone. The change can only merge when 252 on top of the Neutron API backbone. The change can only merge when
253 there is a released version of neutron-lib. 253 there is a released version of neutron-lib.
254 254
255 * How to integrate into the openstack release: every project in the 255* How to integrate into the openstack release: every project in the
256 Stadium must have release notes. In order to set up release notes, 256 Stadium must have release notes. In order to set up release notes,
257 please see the patches below for an example on how to set up reno: 257 please see the patches below for an example on how to set up reno:
258 258
259 * https://review.openstack.org/#/c/320904/ 259 * https://review.openstack.org/#/c/320904/
260 * https://review.openstack.org/#/c/243085/ 260 * https://review.openstack.org/#/c/243085/
261 261
262 For release documentation related to Neutron, please check the 262 For release documentation related to Neutron, please check the
263 `Neutron policies document <http://docs.openstack.org/developer/neutron/#neutron-policies>`_. 263 `Neutron policies document <http://docs.openstack.org/developer/neutron/#neutron-policies>`_.
264 Once, everything is set up and your project is released, make sure 264 Once, everything is set up and your project is released, make sure
265 you see an entry on the release page (e.g. `Ocata <http://releases.openstack.org/ocata/index.html#other-projects>`_. 265 you see an entry on the release page (e.g. `Ocata <http://releases.openstack.org/ocata/index.html#other-projects>`_.
266 Make sure you release according to the project declared release 266 Make sure you release according to the project declared release
267 `model <http://governance.openstack.org/reference/projects/neutron.html#deliverables-and-tags>`_. 267 `model <http://governance.openstack.org/reference/projects/neutron.html#deliverables-and-tags>`_.
268 268
269 * How to port OpenStack Client over to python-neutronclient: client 269* How to port OpenStack Client over to python-neutronclient: client
270 API bindings and client command line interface support must be 270 API bindings and client command line interface support must be
271 developed in python-neutronclient under `osc module <https://github.com/openstack/python-neutronclient/tree/master/neutronclient/osc/v2>`_. 271 developed in python-neutronclient under `osc module <https://github.com/openstack/python-neutronclient/tree/master/neutronclient/osc/v2>`_.
272 If your project requires one or both, consider looking at the 272 If your project requires one or both, consider looking at the
273 following example on how to contribute these two python-neutronclient 273 following example on how to contribute these two python-neutronclient
274 according to the OSC framework and guidelines: 274 according to the OSC framework and guidelines:
275 275
276 * https://review.openstack.org/#/c/340624/ 276 * https://review.openstack.org/#/c/340624/
277 * https://review.openstack.org/#/c/340763/ 277 * https://review.openstack.org/#/c/340763/
278 * https://review.openstack.org/#/c/352653/ 278 * https://review.openstack.org/#/c/352653/
279 279
280 More information on how to develop python-openstackclient plugins 280 More information on how to develop python-openstackclient plugins
281 can be found on the following links: 281 can be found on the following links:
282 282
283 * http://docs.openstack.org/developer/python-openstackclient/plugins.html 283 * http://docs.openstack.org/developer/python-openstackclient/plugins.html
284 * http://docs.openstack.org/developer/python-openstackclient/humaninterfaceguide.html 284 * http://docs.openstack.org/developer/python-openstackclient/humaninterfaceguide.html
285 285
286 It is worth prefixing the commands being added with the keyword 286 It is worth prefixing the commands being added with the keyword
287 `network <https://review.openstack.org/#/c/340624/10/setup.cfg>`_ to 287 `network <https://review.openstack.org/#/c/340624/10/setup.cfg>`_ to
288 avoid potential clash with other commands with similar names. This 288 avoid potential clash with other commands with similar names. This
289 is only required if the command object name is highly likely to have 289 is only required if the command object name is highly likely to have
290 an ambiguous meaning. 290 an ambiguous meaning.