diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 7f62f3f6f..52c51deef 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -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 `_ diff --git a/HACKING.rst b/HACKING.rst index e08eb5422..6f94c82d3 100644 --- a/HACKING.rst +++ b/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 `_ diff --git a/README.rst b/README.rst index 86f6ba868..4bfc09d85 100644 --- a/README.rst +++ b/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 . +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: . This includes: +Code is available on git.openstack.org at: +. - -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 `_ diff --git a/TESTING.rst b/TESTING.rst index 9c0d167e9..9df8dc22f 100644 --- a/TESTING.rst +++ b/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 `_. - -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 `_