Update documentation files for FWaaS

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: Ic287177dd9130dfcce97400532b40712af97a307
This commit is contained in:
Kyle Mestery 2014-12-15 12:54:24 +00:00
parent 48e027cad8
commit 28eec97e49
4 changed files with 23 additions and 269 deletions

View File

@ -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-fwaas:
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>`_

View File

@ -1,33 +1,7 @@
Neutron Style Commandments
=======================
Neutron FWaaS 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-fwaas:
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>`_

View File

@ -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 Firewall as a Service
(FWaaS) 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-fwaas>.
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>`_

View File

@ -1,205 +1,8 @@
Testing Neutron
=============================================================
Testing Neutron FWaaS
=====================
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-fwaas 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>`_