Merge "Added some docs about hacking and testing"

CONTRIBUTING.rst

@@ -1,3 +1,6 @@
+Before You Start
+================
+
 If you would like to contribute to the development of OpenStack,
 you must follow the steps in this page:
 
@@ -9,8 +12,23 @@ the workflow documented at:
 
    http://docs.openstack.org/infra/manual/developers.html#development-workflow
 
-Pull requests submitted through GitHub will be ignored.
+Where to Start
+==============
 
-Bugs should be filed on Launchpad, not GitHub:
+Senlin maintains a `TODO` file under the root directory, where developers
+can add new items, claim existing items and remove items that are completed.
+You may want to check if there are items you can pick by signing your name
+there.
+
+Reporting Bugs
+==============
+
+Bugs should be filed on Launchpad:
 
    https://bugs.launchpad.net/senlin
+
+Meet the Developers
+===================
+
+Real-time communication among developers are mostly done via IRC.
+The team is using the #senlin channel on freenode.net.

HACKING.rst

@@ -8,7 +8,15 @@ Senlin Style Commandments
 Senlin Specific Commandments
 ----------------------------
 
-None so far
+Working on APIs
+---------------
+
+If you are proposing new APIs or fixes to existing APIs, please spend some
+time reading the guidelines published by the API WorkGroup:
+
+http://git.openstack.org/cgit/openstack/api-wg/tree/guidelines
+
+Any work on improving Senlin's APIs to conform to the guidelines are welcomed.
 
 Creating Unit Tests
 -------------------
@@ -18,20 +26,24 @@ 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.
 
-For more information on creating unit tests and utilizing the testing
-infrastructure in OpenStack Senlin, please read senlin/tests/testing-overview.txt.
+For more information on creating and running unit tests , please read
+senlin/doc/source/testing.txt.
 
 
 Running Tests
 -------------
-The testing system is based on a combination of tox and testr. The canonical
-approach to running tests is to simply run the command `tox`. This will
-create virtual environments, populate them with dependencies and run all of
-the tests that OpenStack CI systems run. Behind the scenes, tox is running
-`testr run --parallel`, but is set up such that you can supply any additional
-testr arguments that are needed to tox. For example, you can run:
-`tox -- --analyze-isolation` to cause tox to tell testr to add
---analyze-isolation to its argument list.
+
+The testing system is based on a combination of `tox` and `testr`. The
+canonical approach to running tests is to simply run the command `tox`.
+This will create virtual environments, populate them with dependencies and
+run all of the tests that OpenStack CI systems run.
+
+Behind the scenes, `tox` is running `testr run --parallel`, but is set up
+such that you can supply any additional `testr` arguments that are needed
+by `tox`. For example, the following command makes `tox` to tell `testr` to
+add `--analyze-isolation` to its argument list::
+
+  tox -- --analyze-isolation
 
 It is also possible to run the tests inside of a virtual environment
 you have created, or it is possible that you have all of the dependencies

doc/source/index.rst

@@ -49,6 +49,7 @@ Getting Started
     getting_started/index
     policies/index
     profiles/index
+    testing
     glossary
 
 Man Pages

doc/source/testing.txt

@@ -0,0 +1,72 @@
+Senlin testing
+==============
+
+All unit tests are to be placed in the senlin/tests directory, and tests can
+be organized by the targeted subsystems/modules. Each subsystem directory
+must contain a separate blank __init__.py for tests discovery to function.
+
+An example directory structure::
+
+  senlin
+    `-- tests
+          |-- db
+          |   |-- __init__.py
+          |   |-- test_cluster_api.py
+          |   `-- test_node_api.py
+          |-- engine
+          |   |-- __init__.py
+          |   |-- test_clusters.py
+          |   `-- test_nodes.py
+          |-- __init__.py
+          `-- test_utils.py
+
+Implementing a test
+-------------------
+
+Testrepository - http://pypi.python.org/pypi/testrepository is used to
+find and run tests, parallelize their runs, and record timing/results.
+
+If new dependencies are introduced upon the development of a test, the
+test-requirements.txt file needs to be updated so that the virtual
+environment will be able to successfully execute all tests.
+
+The `test-requirements.txt` file needs to be synchronized with the
+openstack/global-requirements project. Developers should try avoid 
+introducing additional package dependencies unless forced to.
+
+Running Tests
+-------------
+
+Senlin uses `tox` for running unit tests, as practiced by many other OpenStack
+projects::
+
+  $ tox
+
+This by default will run unit tests suite with Python 2.7 and PEP8/HACKING
+style checks. To run only one type of tests you can explicitly provide `tox`
+with the test environment to use::
+
+  $ tox -epy27 # test suite on python 2.7
+  $ tox -epep8 # run full source code checker
+
+To run only a subset of tests, you can provide `tox` with a regex argument::
+
+  $ tox -epy27 -- VolumeTests
+
+To use debugger like `pdb` during test run, you have to run tests directly
+with other, non-concurrent test runner instead of `testr`.
+That also presumes that you have a virtual env with all senlin dependencies
+installed and configured.
+
+Below is an example bash script using `testtools` test runner that also allows
+running single tests by providing a regex::
+
+  #! /usr/bin/env sh
+  testlist=$(mktemp)
+  testr list-tests "$1" > $testlist
+  python -m testtools.run --load-list $testlist
+
+A more convenient way to run specific test is to name the unit test directly,
+as shown below::
+
+  $ python -m testtools.run senlin.tests.db.test_cluster_api