Update documentation files for VPNaaS
The README file was not updated during the services split to accurately reflect what project this was. Also, update CONTRIBUTING.rst, HACKING.rst, and TESTING.rst to point to their Neutron counterparts. This makes maintaining a single copy easier. Change-Id: I4d9cee887753fc6d7b8b1116deebd2a90faa0f3b
This commit is contained in:
Kyle Mestery
parent
8fc8f7f7d5
commit
578c4c554b
@ -1,16 +1,4 @@
|
||||
If you would like to contribute to the development of OpenStack,
|
||||
you must follow the steps documented at:
|
||||
Please see the Neutron CONTRIBUTING.rst file for how to contribute to
|
||||
neutron-vpnaas:
|
||||
|
||||
http://docs.openstack.org/infra/manual/developers.html#development-workflow
|
||||
|
||||
Once those steps have been completed, changes to OpenStack
|
||||
should be submitted for review via the Gerrit tool, following
|
||||
the workflow documented at:
|
||||
|
||||
http://docs.openstack.org/infra/manual/developers.html#development-workflow
|
||||
|
||||
Pull requests submitted through GitHub will be ignored.
|
||||
|
||||
Bugs should be filed on Launchpad, not GitHub:
|
||||
|
||||
https://bugs.launchpad.net/neutron
|
||||
`Neutron CONTRIBUTING.rst <http://git.openstack.org/cgit/openstack/neutron/tree/CONTRIBUTING.rst>`_
|
||||
|
||||
36
HACKING.rst
36
HACKING.rst
@ -1,33 +1,7 @@
|
||||
Neutron Style Commandments
|
||||
=======================
|
||||
Neutron VPNaaS Style Commandments
|
||||
=================================
|
||||
|
||||
- Step 1: Read the OpenStack Style Commandments
|
||||
http://docs.openstack.org/developer/hacking/
|
||||
- Step 2: Read on
|
||||
Please see the Neutron HACKING.rst file for style commandments for
|
||||
neutron-vpnaas:
|
||||
|
||||
Neutron Specific Commandments
|
||||
--------------------------
|
||||
|
||||
- [N319] Validate that debug level logs are not translated
|
||||
- [N320] Validate that LOG messages, except debug ones, have translations
|
||||
- [N321] Validate that jsonutils module is used instead of json
|
||||
- [N322] We do not use @authors tags in source files. We have git to track
|
||||
authorship.
|
||||
- [N323] Detect common errors with assert_called_once_with
|
||||
|
||||
Creating Unit Tests
|
||||
-------------------
|
||||
For every new feature, unit tests should be created that both test and
|
||||
(implicitly) document the usage of said feature. If submitting a patch for a
|
||||
bug that had no unit test, a new passing unit test should be added. If a
|
||||
submitted bug fix does have a unit test, be sure to add a new one that fails
|
||||
without the patch and passes with the patch.
|
||||
|
||||
All unittest classes must ultimately inherit from testtools.TestCase. In the
|
||||
Neutron test suite, this should be done by inheriting from
|
||||
neutron.tests.base.BaseTestCase.
|
||||
|
||||
All setUp and tearDown methods must upcall using the super() method.
|
||||
tearDown methods should be avoided and addCleanup calls should be preferred.
|
||||
Never manually create tempfiles. Always use the tempfile fixtures from
|
||||
the fixture library to ensure that they are cleaned up.
|
||||
`Neutron HACKING.rst <http://git.openstack.org/cgit/openstack/neutron/tree/HACKING.rst>`_
|
||||
|
||||
29
README.rst
29
README.rst
@ -1,30 +1,19 @@
|
||||
Welcome!
|
||||
========
|
||||
|
||||
You have come across a cloud computing network fabric controller. It has
|
||||
identified itself as "Neutron." It aims to tame your (cloud) networking!
|
||||
This package contains the code for the Neutron VPN as a Service
|
||||
(VPNaaS) service. This includes third-party drivers. This package
|
||||
requires Neutron to run.
|
||||
|
||||
External Resources:
|
||||
===================
|
||||
|
||||
The homepage for Neutron is: http://launchpad.net/neutron. Use this
|
||||
site for asking for help, and filing bugs. Code is available on
|
||||
git.openstack.org at <http://git.openstack.org/cgit/openstack/neutron>.
|
||||
site for asking for help, and filing bugs. We use a single Launchpad
|
||||
page for all Neutron projects.
|
||||
|
||||
The latest and most in-depth documentation on how to use Neutron is
|
||||
available at: <http://docs.openstack.org>. This includes:
|
||||
Code is available on git.openstack.org at:
|
||||
<http://git.openstack.org/cgit/openstack/neutron-vpnaas.
|
||||
|
||||
Neutron Administrator Guide
|
||||
http://docs.openstack.org/admin-guide-cloud/content/ch_networking.html
|
||||
|
||||
Neutron API Reference:
|
||||
http://docs.openstack.org/api/openstack-network/2.0/content/
|
||||
|
||||
Current Neutron developer documentation is available at:
|
||||
http://wiki.openstack.org/NeutronDevelopment
|
||||
|
||||
For help on usage and hacking of Neutron, please send mail to
|
||||
<mailto:openstack-dev@lists.openstack.org>.
|
||||
|
||||
For information on how to contribute to Neutron, please see the
|
||||
contents of the CONTRIBUTING.rst file.
|
||||
Please refer to Neutron documentation for more information:
|
||||
`Neutron README.rst <http://git.openstack.org/cgit/openstack/neutron/tree/README.rst>`_
|
||||
|
||||
209
TESTING.rst
209
TESTING.rst
@ -1,205 +1,8 @@
|
||||
Testing Neutron
|
||||
=============================================================
|
||||
Testing Neutron VPNaaS
|
||||
======================
|
||||
|
||||
Overview
|
||||
--------
|
||||
Please see the TESTING.rst file for the Neutron project itself. This will have
|
||||
the latest up to date instructions for how to test Neutron, and will
|
||||
be applicable to neutron-vpnaas as well:
|
||||
|
||||
The unit tests (neutron/test/unit/) are meant to cover as much code as
|
||||
possible and should be executed without the service running. They are
|
||||
designed to test the various pieces of the neutron tree to make sure
|
||||
any new changes don't break existing functionality.
|
||||
|
||||
The functional tests (neutron/tests/functional/) are intended to
|
||||
validate actual system interaction. Mocks should be used sparingly,
|
||||
if at all. Care should be taken to ensure that existing system
|
||||
resources are not modified and that resources created in tests are
|
||||
properly cleaned up.
|
||||
|
||||
Development process
|
||||
-------------------
|
||||
|
||||
It is expected that any new changes that are proposed for merge
|
||||
come with tests for that feature or code area. Ideally any bugs
|
||||
fixes that are submitted also have tests to prove that they stay
|
||||
fixed! In addition, before proposing for merge, all of the
|
||||
current tests should be passing.
|
||||
|
||||
Virtual environments
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Testing OpenStack projects, including Neutron, is made easier with `DevStack <https://git.openstack.org/cgit/openstack-dev/devstack>`_.
|
||||
|
||||
Create a machine (such as a VM or Vagrant box) running a distribution supported
|
||||
by DevStack and install DevStack there. For example, there is a Vagrant script
|
||||
for DevStack at https://github.com/bcwaldon/vagrant_devstack.
|
||||
|
||||
.. note::
|
||||
|
||||
If you prefer not to use DevStack, you can still check out source code on your local
|
||||
machine and develop from there.
|
||||
|
||||
|
||||
Running unit tests
|
||||
------------------
|
||||
|
||||
There are three mechanisms for running tests: run_tests.sh, tox,
|
||||
and nose. 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 `nose`
|
||||
~~~~~~~~~~~
|
||||
|
||||
You can use `nose`_ to run individual tests, as well as use for debugging
|
||||
portions of your code::
|
||||
|
||||
source .venv/bin/activate
|
||||
pip install nose
|
||||
nosetests
|
||||
|
||||
There are disadvantages to running Nose - the tests are run sequentially, so
|
||||
race condition bugs will not be triggered, and the full test suite will
|
||||
take significantly longer than tox & testr. The upside is that testr has
|
||||
some rough edges when it comes to diagnosing errors and failures, and there is
|
||||
no easy way to set a breakpoint in the Neutron code, and enter an
|
||||
interactive debugging session while using testr.
|
||||
|
||||
.. _nose: https://nose.readthedocs.org/en/latest/index.html
|
||||
|
||||
With `tox`
|
||||
~~~~~~~~~~
|
||||
|
||||
Neutron, 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 (2.6, 2.7, 3.3, etc).
|
||||
|
||||
Testr handles the parallel execution of series of test cases as well as
|
||||
the tracking of long-running tests and other things.
|
||||
|
||||
Running unit tests is as easy as executing this in the root directory of the
|
||||
Neutron source code::
|
||||
|
||||
tox
|
||||
|
||||
To run functional tests that do not require sudo privileges or
|
||||
specific-system dependencies::
|
||||
|
||||
tox -e functional
|
||||
|
||||
To run all the functional tests in an environment that has been configured
|
||||
by devstack to support sudo and system-specific dependencies::
|
||||
|
||||
tox -e dsvm-functional
|
||||
|
||||
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
|
||||
|
||||
|
||||
Running individual tests
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For running individual test modules or cases, you just need to pass
|
||||
the dot-separated path to the module you want as an argument to it.
|
||||
|
||||
For executing a specific test case, specify the name of the test case
|
||||
class separating it from the module path with a colon.
|
||||
|
||||
For example, the following would run only the JSONV2TestCase tests from
|
||||
neutron/tests/unit/test_api_v2.py::
|
||||
|
||||
$ ./run_tests.sh neutron.tests.unit.test_api_v2.JSONV2TestCase
|
||||
|
||||
or::
|
||||
|
||||
$ tox -e py27 neutron.tests.unit.test_api_v2.JSONV2TestCase
|
||||
|
||||
Adding more tests
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
Neutron has a fast growing code base and there is plenty of areas that
|
||||
need to be covered by unit and functional tests.
|
||||
|
||||
To get a grasp of the areas where tests are needed, you can check
|
||||
current coverage by running::
|
||||
|
||||
$ ./run_tests.sh -c
|
||||
|
||||
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 neutron 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
|
||||
`Neutron TESTING.rst <http://git.openstack.org/cgit/openstack/neutron/tree/TESTING.rst>`_
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user