Adding dir structure for developer reference docs
This patch is in response to prior discussion in the weekly IRC team meeting. The patch does not actually add any documentation (apart from the bits on testing and dev env setup). It does propose topics in the index.rst for documents that need to added for the existing components. These will be added by the team as follow-up patches. For any patch that adds a new feature or modifies an existing feature it will be required to submit a devref rst document as a part of that patch. This document should be posted in the doc/source/devref/ location. There isn's a specific format for the document, but it is expected that the document adequately explains the design of the feature that is being implemented such that its easy for the rest of the team to review, maintain, and enhance the implementation. Change-Id: Ifc32c330d754f623c403fb0c9a5f5c639cce41db
This commit is contained in:
Sumit Naiksatam
parent
88bae4c30f
commit
5c0f28bd88
187
TESTING.rst
Normal file
187
TESTING.rst
Normal file
@ -0,0 +1,187 @@
|
|||||||
|
..
|
||||||
|
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||||
|
not use this file except in compliance with the License. You may obtain
|
||||||
|
a copy of the License at
|
||||||
|
|
||||||
|
http://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
|
||||||
|
Unless required by applicable law or agreed to in writing, software
|
||||||
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||||
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||||
|
License for the specific language governing permissions and limitations
|
||||||
|
under the License.
|
||||||
|
|
||||||
|
|
||||||
|
Convention for heading levels in GBP devref:
|
||||||
|
======= Heading 0 (reserved for the title in a document)
|
||||||
|
------- Heading 1
|
||||||
|
~~~~~~~ Heading 2
|
||||||
|
+++++++ Heading 3
|
||||||
|
''''''' Heading 4
|
||||||
|
(Avoid deeper levels because they do not render well.)
|
||||||
|
|
||||||
|
|
||||||
|
Testing GBP
|
||||||
|
===============
|
||||||
|
|
||||||
|
|
||||||
|
Running Tests
|
||||||
|
-------------
|
||||||
|
|
||||||
|
There are two mechanisms for running tests: run_tests.sh, and tox.
|
||||||
|
Before submitting a patch for review you should always
|
||||||
|
ensure all test pass; a tox run is triggered by the jenkins gate
|
||||||
|
executed on gerrit for each patch pushed for review.
|
||||||
|
|
||||||
|
With these mechanisms you can either run the tests in the standard
|
||||||
|
environment or create a virtual environment to run them in.
|
||||||
|
|
||||||
|
By default after running all of the tests, any pep8 errors
|
||||||
|
found in the tree will be reported.
|
||||||
|
|
||||||
|
|
||||||
|
With `run_tests.sh`
|
||||||
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
You can use the `run_tests.sh` script in the root source directory to execute
|
||||||
|
tests in a virtualenv::
|
||||||
|
|
||||||
|
./run_tests -V
|
||||||
|
|
||||||
|
|
||||||
|
With `tox`
|
||||||
|
~~~~~~~~~~
|
||||||
|
|
||||||
|
GBP, like other OpenStack projects, uses `tox`_ for managing the virtual
|
||||||
|
environments for running test cases. It uses `Testr`_ for managing the running
|
||||||
|
of the test cases.
|
||||||
|
|
||||||
|
Tox handles the creation of a series of `virtualenvs`_ that target specific
|
||||||
|
versions of Python.
|
||||||
|
|
||||||
|
Testr handles the parallel execution of series of test cases as well as
|
||||||
|
the tracking of long-running tests and other things.
|
||||||
|
|
||||||
|
For more information on the standard Tox-based test infrastructure used by
|
||||||
|
OpenStack and how to do some common test/debugging procedures with Testr,
|
||||||
|
see this wiki page:
|
||||||
|
|
||||||
|
https://wiki.openstack.org/wiki/Testr
|
||||||
|
|
||||||
|
.. _Testr: https://wiki.openstack.org/wiki/Testr
|
||||||
|
.. _tox: http://tox.readthedocs.org/en/latest/
|
||||||
|
.. _virtualenvs: https://pypi.python.org/pypi/virtualenv
|
||||||
|
|
||||||
|
PEP8 and Unit Tests
|
||||||
|
+++++++++++++++++++
|
||||||
|
|
||||||
|
Running pep8 and unit tests is as easy as executing this in the root
|
||||||
|
directory of the GBP source code::
|
||||||
|
|
||||||
|
tox
|
||||||
|
|
||||||
|
To run only pep8::
|
||||||
|
|
||||||
|
tox -e pep8
|
||||||
|
|
||||||
|
To restrict pep8 check to only the files altered by the latest patch changes::
|
||||||
|
|
||||||
|
tox -e pep8 HEAD~1
|
||||||
|
|
||||||
|
To run only the unit tests::
|
||||||
|
|
||||||
|
tox -e py27
|
||||||
|
|
||||||
|
|
||||||
|
Running Individual Tests
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
For running individual test modules, cases or tests, you just need to pass
|
||||||
|
the dot-separated path you want as an argument to it.
|
||||||
|
|
||||||
|
For example, the following would run only a single test or test case::
|
||||||
|
|
||||||
|
$ ./run_tests.sh gbpservice.neutron.tests.unit.test_extension_group_policy
|
||||||
|
$ ./run_tests.sh gbpservice.neutron.tests.unit.test_extension_group_policy.GroupPolicyExtensionTestCase
|
||||||
|
$ ./run_tests.sh gbpservice.neutron.tests.unit.test_extension_group_policy.GroupPolicyExtensionTestCase.test_create_policy_target
|
||||||
|
|
||||||
|
or::
|
||||||
|
|
||||||
|
$ tox -e py27 gbpservice.neutron.tests.unit.test_extension_group_policy
|
||||||
|
$ tox -e py27 gbpservice.neutron.tests.unit.test_extension_group_policy.GroupPolicyExtensionTestCase
|
||||||
|
$ tox -e py27 gbpservice.neutron.tests.unit.test_extension_group_policy.GroupPolicyExtensionTestCase.test_create_policy_target
|
||||||
|
|
||||||
|
If you want to pass other arguments to ostestr, you can do the following::
|
||||||
|
$ tox -e -epy27 -- --regex gbpservice.neutron.tests.unit.test_extension_group_policy --serial
|
||||||
|
|
||||||
|
|
||||||
|
Coverage
|
||||||
|
--------
|
||||||
|
|
||||||
|
To get a grasp of the areas where tests are needed, you can check
|
||||||
|
current unit tests coverage by running::
|
||||||
|
|
||||||
|
$ ./run_tests.sh -c
|
||||||
|
|
||||||
|
or by running::
|
||||||
|
|
||||||
|
$ tox -ecover
|
||||||
|
|
||||||
|
Note that this is also useful to run before submitting a new patchset
|
||||||
|
to ensure that the new code you are introducing has adequate unit test
|
||||||
|
coverage.
|
||||||
|
|
||||||
|
|
||||||
|
Debugging
|
||||||
|
---------
|
||||||
|
|
||||||
|
By default, calls to pdb.set_trace() will be ignored when tests
|
||||||
|
are run. For pdb statements to work, invoke run_tests as follows::
|
||||||
|
|
||||||
|
$ ./run_tests.sh -d [test module path]
|
||||||
|
|
||||||
|
It's possible to debug tests in a tox environment::
|
||||||
|
|
||||||
|
$ tox -e venv -- python -m testtools.run [test module path]
|
||||||
|
|
||||||
|
Tox-created virtual environments (venv's) can also be activated
|
||||||
|
after a tox run and reused for debugging::
|
||||||
|
|
||||||
|
$ tox -e venv
|
||||||
|
$ . .tox/venv/bin/activate
|
||||||
|
$ python -m testtools.run [test module path]
|
||||||
|
|
||||||
|
Tox packages and installs the GBP source tree in a given venv
|
||||||
|
on every invocation, but if modifications need to be made between
|
||||||
|
invocation (e.g. adding more pdb statements), it is recommended
|
||||||
|
that the source tree be installed in the venv in editable mode::
|
||||||
|
|
||||||
|
# run this only after activating the venv
|
||||||
|
$ pip install --editable .
|
||||||
|
|
||||||
|
Editable mode ensures that changes made to the source tree are
|
||||||
|
automatically reflected in the venv, and that such changes are not
|
||||||
|
overwritten during the next tox run.
|
||||||
|
|
||||||
|
Post-mortem Debugging
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Setting OS_POST_MORTEM_DEBUGGER in the shell environment will ensure
|
||||||
|
that the debugger .post_mortem() method will be invoked on test failure::
|
||||||
|
|
||||||
|
$ OS_POST_MORTEM_DEBUGGER=pdb ./run_tests.sh -d [test module path]
|
||||||
|
|
||||||
|
Supported debuggers are pdb, and pudb. Pudb is full-screen, console-based
|
||||||
|
visual debugger for Python which let you inspect variables, the stack,
|
||||||
|
and breakpoints in a very visual way, keeping a high degree of compatibility
|
||||||
|
with pdb::
|
||||||
|
|
||||||
|
$ ./.venv/bin/pip install pudb
|
||||||
|
|
||||||
|
$ OS_POST_MORTEM_DEBUGGER=pudb ./run_tests.sh -d [test module path]
|
||||||
|
|
||||||
|
References
|
||||||
|
~~~~~~~~~~
|
||||||
|
|
||||||
|
.. [#pudb] PUDB debugger:
|
||||||
|
https://pypi.python.org/pypi/pudb
|
||||||
55
doc/source/devref/development.environment.rst
Normal file
55
doc/source/devref/development.environment.rst
Normal file
@ -0,0 +1,55 @@
|
|||||||
|
..
|
||||||
|
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||||
|
not use this file except in compliance with the License. You may obtain
|
||||||
|
a copy of the License at
|
||||||
|
|
||||||
|
http://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
|
||||||
|
Unless required by applicable law or agreed to in writing, software
|
||||||
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||||
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||||
|
License for the specific language governing permissions and limitations
|
||||||
|
under the License.
|
||||||
|
|
||||||
|
|
||||||
|
Convention for heading levels in GBP devref:
|
||||||
|
======= Heading 0 (reserved for the title in a document)
|
||||||
|
------- Heading 1
|
||||||
|
~~~~~~~ Heading 2
|
||||||
|
+++++++ Heading 3
|
||||||
|
''''''' Heading 4
|
||||||
|
(Avoid deeper levels because they do not render well.)
|
||||||
|
|
||||||
|
|
||||||
|
Setting Up a Development Environment
|
||||||
|
====================================
|
||||||
|
|
||||||
|
This page describes how to setup a working Python development
|
||||||
|
environment that can be used in developing GBP on Ubuntu, Fedora or
|
||||||
|
Mac OS X. These instructions assume you're already familiar with
|
||||||
|
Git and Gerrit, which is a code repository mirror and code review toolset
|
||||||
|
, however if you aren't please see `this Git tutorial`_ for an introduction
|
||||||
|
to using Git and `this guide`_ for a tutorial on using Gerrit and Git for
|
||||||
|
code contribution to OpenStack projects.
|
||||||
|
|
||||||
|
.. _this Git tutorial: http://git-scm.com/book/en/Getting-Started
|
||||||
|
.. _this guide: http://docs.openstack.org/infra/manual/developers.html#development-workflow
|
||||||
|
|
||||||
|
Following these instructions will allow you to run the GBP unit
|
||||||
|
tests. If you want to be able to run GBP in a full OpenStack environment,
|
||||||
|
you can use the excellent `DevStack`_ project to do so. There is a wiki page
|
||||||
|
that describes `setting up GBP using DevStack`_.
|
||||||
|
|
||||||
|
.. _DevStack: https://git.openstack.org/cgit/openstack-dev/devstack
|
||||||
|
.. _setting up GBP using Devstack: https://wiki.openstack.org/wiki/GroupBasedPolicy/InstallDevstack
|
||||||
|
|
||||||
|
Getting the code
|
||||||
|
----------------
|
||||||
|
|
||||||
|
Grab the code::
|
||||||
|
|
||||||
|
git clone git://git.openstack.org/openstack/group-based-policy.git
|
||||||
|
cd group-based-policy
|
||||||
|
|
||||||
|
|
||||||
|
.. include:: ../../../TESTING.rst
|
||||||
3
doc/source/devref/images/README
Normal file
3
doc/source/devref/images/README
Normal file
@ -0,0 +1,3 @@
|
|||||||
|
This is a placeholder file until images get added to this directory.
|
||||||
|
When the first image is added to this director, this README file
|
||||||
|
can be deleted.
|
||||||
60
doc/source/devref/index.rst
Normal file
60
doc/source/devref/index.rst
Normal file
@ -0,0 +1,60 @@
|
|||||||
|
..
|
||||||
|
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||||
|
not use this file except in compliance with the License. You may obtain
|
||||||
|
a copy of the License at
|
||||||
|
|
||||||
|
http://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
|
||||||
|
Unless required by applicable law or agreed to in writing, software
|
||||||
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||||
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||||
|
License for the specific language governing permissions and limitations
|
||||||
|
under the License.
|
||||||
|
|
||||||
|
Developer Guide
|
||||||
|
===============
|
||||||
|
|
||||||
|
In the Developer Guide, you will find information on the design and
|
||||||
|
implementation of Group Based Policy's software components.
|
||||||
|
|
||||||
|
|
||||||
|
Programming HowTos and Tutorials
|
||||||
|
--------------------------------
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 3
|
||||||
|
|
||||||
|
development.environment
|
||||||
|
|
||||||
|
|
||||||
|
GBP Design
|
||||||
|
----------
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 3
|
||||||
|
|
||||||
|
gbp_resource_model
|
||||||
|
gbp_plugin_and_driver_architecture
|
||||||
|
gbp_driver_extensions
|
||||||
|
implicit_mapping_policy_driver
|
||||||
|
resource_mapping_policy_driver
|
||||||
|
gbp_external_connectivity
|
||||||
|
gbp_service_chaining_model
|
||||||
|
gbp_node_composition_plugin_and_driver_architecture
|
||||||
|
gbp_traffic_stitching_plumber
|
||||||
|
|
||||||
|
|
||||||
|
Module Reference
|
||||||
|
----------------
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 3
|
||||||
|
|
||||||
|
.. todo::
|
||||||
|
|
||||||
|
Add in all the big modules as automodule indexes.
|
||||||
|
|
||||||
|
|
||||||
|
Indices and tables
|
||||||
|
------------------
|
||||||
|
|
||||||
|
* :ref:`genindex`
|
||||||
|
* :ref:`modindex`
|
||||||
|
* :ref:`search`
|
||||||
Loading…
Reference in New Issue
Block a user