From 40f39557b3cedd21828b548e6f7cf57c8e6b8f76 Mon Sep 17 00:00:00 2001 From: Lorin Hochstein Date: Sat, 26 Nov 2011 08:43:16 -0500 Subject: [PATCH] New docs: unit tests, Launchpad, Gerrit, Jenkins Documented how to run unit tests Added docs about what's on Launchpad Added docs on Gerrit with pointers to wiki. Added docs on Jenkins: how to access, what it does Clarified that running unit tests doesn't mean you can fully run OpenStack. Change-Id: I33fa9d2f271631a1a9aceaa5d4fd465198bf51d4 --- doc/source/community.rst | 17 ++- doc/source/devref/development.environment.rst | 16 +- doc/source/devref/gerrit.rst | 16 ++ doc/source/devref/index.rst | 11 +- doc/source/devref/jenkins.rst | 36 +++++ doc/source/devref/launchpad.rst | 54 +++++++ doc/source/devref/unit_tests.rst | 143 ++++++++++++++++++ 7 files changed, 282 insertions(+), 11 deletions(-) create mode 100644 doc/source/devref/gerrit.rst create mode 100644 doc/source/devref/jenkins.rst create mode 100644 doc/source/devref/launchpad.rst create mode 100644 doc/source/devref/unit_tests.rst diff --git a/doc/source/community.rst b/doc/source/community.rst index 8ae0f73e699d..76ede0d87d9e 100644 --- a/doc/source/community.rst +++ b/doc/source/community.rst @@ -18,7 +18,7 @@ Getting Involved ================ -The OpenStack community for Nova is a very friendly group and there are places online to join in with the +The OpenStack community for Nova is a very friendly group and there are places online to join in with the community. Feel free to ask questions. This document points you to some of the places where you can communicate with people. @@ -34,8 +34,8 @@ Contributing Code ----------------- To contribute code, sign up for a Launchpad account and sign a contributor license agreement, -available on the `OpenStack Wiki `_. Once the CLA is signed you -can contribute code through the Bazaar version control system which is related to your Launchpad +available on the `OpenStack Wiki `_. Once the CLA is signed you +can contribute code through the Bazaar version control system which is related to your Launchpad account. See the :doc:`devref/development.environment` page to get started. #openstack on Freenode IRC Network @@ -43,8 +43,8 @@ account. See the :doc:`devref/development.environment` page to get started. There is a very active chat channel at ``_. This is usually the best place to ask questions and find your way around. IRC stands for Internet Relay -Chat and it is a way to chat online in real time. You can also ask a question and come back to the -log files to read the answer later. Logs for the #openstack IRC channel are stored at +Chat and it is a way to chat online in real time. You can also ask a question and come back to the +log files to read the answer later. Logs for the #openstack IRC channel are stored at ``_. OpenStack Wiki @@ -54,19 +54,20 @@ The wiki is a living source of knowledge. It is edited by the community, and has collections of links and other sources of information. Typically the pages are a good place to write drafts for specs or documentation, describe a blueprint, or collaborate with others. -`OpenStack Wiki `_ +* `OpenStack Wiki `_ Nova on Github -------------- -Github is a code hosting service that hosts the Nova source code. +Github is a code hosting service that hosts the Nova source code. * `Github Nova page `_ Nova on Launchpad ----------------- -From Launchpad you can report bugs, ask questions, and register blueprints (feature requests). +From Launchpad you can report bugs, ask questions, and register blueprints (feature requests). +See :doc:`devref/launchpad` for more details. * `Launchpad Nova Page `_ diff --git a/doc/source/devref/development.environment.rst b/doc/source/devref/development.environment.rst index f7d23b60a128..1e81b4cfa1e3 100644 --- a/doc/source/devref/development.environment.rst +++ b/doc/source/devref/development.environment.rst @@ -19,10 +19,18 @@ Setting Up a Development Environment ==================================== This page describes how to setup a working Python development environment that -can be used in developing on OpenStack on Ubuntu, Fedora or Mac OS X. These -instructions assume you're already familiar with git. Refer to +can be used in developing nova on Ubuntu, Fedora or Mac OS X. These +instructions assume you're already familiar with git. Refer to http://wiki.openstack.org/GettingTheCode for additional information. +Following these instructions will allow you to run the nova unit tests. If you +want to be able to run nova (i.e., launch VM instances), you will also need to +install libvirt and at least one of the `supported +hypervisors`_. Running +nova is currently only supported on Linux, although you can run +the unit tests on Mac OS X. See :doc:`quickstart` for how to get a working +version of OpenStack Compute running as quickly as possible. + Virtual environments -------------------- @@ -52,6 +60,7 @@ On Fedora-based distributions (e.g., Fedora/RHEL/CentOS/Scientific Linux):: sudo yum install python-devel swig openssl-devel python-pip git + Mac OS X Systems ---------------- @@ -97,6 +106,9 @@ environment (hit "y"):: No virtual environment found...create one? (Y/n) +See :doc:`unit_tests` for more details. + +.. _virtualenv: Manually installing and using the virtualenv -------------------------------------------- diff --git a/doc/source/devref/gerrit.rst b/doc/source/devref/gerrit.rst new file mode 100644 index 000000000000..1a33aa167694 --- /dev/null +++ b/doc/source/devref/gerrit.rst @@ -0,0 +1,16 @@ +Code Reviews with Gerrit +======================== + +Nova uses the `Gerrit`_ tool to review proposed code changes. The review site +is http://review.openstack.org. + +Gerrit is a complete replacement for Github pull requests. `All Github pull +requests to the Nova repository will be ignored`. + +See `Gerrit Workflow Quick Reference`_ for information about how to get +started using Gerrit. See `Gerrit, Jenkins and Github`_ for more detailed +documentation on how to work with Gerrit. + +.. _Gerrit: http://code.google.com/p/gerrit +.. _Gerrit, Jenkins and Github: http://wiki.openstack.org/GerritJenkinsGithub +.. _Gerrit Workflow Quick Reference: http://wiki.openstack.org/GerritWorkflow diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst index be1188b78232..cfbde620953c 100644 --- a/doc/source/devref/index.rst +++ b/doc/source/devref/index.rst @@ -27,6 +27,7 @@ Programming HowTos and Tutorials :maxdepth: 3 development.environment + unit_tests addmethod.openstackapi @@ -41,7 +42,15 @@ Background Concepts for Nova multinic zone rabbit - + +Other Resources +--------------- +.. toctree:: + :maxdepth: 3 + + launchpad + gerrit + jenkins API Reference ------------- diff --git a/doc/source/devref/jenkins.rst b/doc/source/devref/jenkins.rst new file mode 100644 index 000000000000..1144f246e43a --- /dev/null +++ b/doc/source/devref/jenkins.rst @@ -0,0 +1,36 @@ +Continuous Integration with Jenkins +=================================== + +Nova uses a `Jenkins`_ server to automate development tasks. The Jenkins +front-end is at http://jenkins.openstack.org. You must have an +account on `Launchpad`_ to be able to access the OpenStack Jenkins site. + +Jenkins performs tasks such as: + +`gate-nova-unittests`_ + Run unit tests on proposed code changes that have been reviewed. + +`gate-nova-pep8`_ + Run PEP8 checks on proposed code changes that have been reviewed. + +`gate-nova-merge`_ + Merge reviewed code into the git repository. + +`nova-coverage`_ + Calculate test coverage metrics. + +`nova-docs`_ + Build this documentation and push it to http://nova.openstack.org. + +`nova-pylint`_ + Run `pylint `_ on the nova code and + report violations. + +.. _Jenkins: http://jenkins-ci.org +.. _Launchpad: http://launchpad.net +.. _gate-nova-merge: https://jenkins.openstack.org/view/Nova/job/gate-nova-merge +.. _gate-nova-pep8: https://jenkins.openstack.org/view/Nova/job/gate-nova-pep8 +.. _gate-nova-unittests: https://jenkins.openstack.org/view/Nova/job/gate-nova-unittests +.. _nova-coverage: https://jenkins.openstack.org/view/Nova/job/nova-coverage +.. _nova-docs: https://jenkins.openstack.org/view/Nova/job/nova-docs +.. _nova-pylint: https://jenkins.openstack.org/job/nova-pylint/ \ No newline at end of file diff --git a/doc/source/devref/launchpad.rst b/doc/source/devref/launchpad.rst new file mode 100644 index 000000000000..e1ab13cb1ca5 --- /dev/null +++ b/doc/source/devref/launchpad.rst @@ -0,0 +1,54 @@ +Project hosting with Launchpad +============================== + +`Launchpad`_ hosts the Nova project. The Nova project homepage on Launchpad is +http://launchpad.net/nova. + +Launchpad credentials +--------------------- + +Creating a login on Launchpad is important even if you don't use the Launchpad +site itself, since Launchpad credentials are used for logging in on several +OpenStack-related sites. These sites include: + + * `Wiki`_ + * Gerrit (see :doc:`gerrit`) + * Jenkins (see :doc:`jenkins`) + +Mailing list +------------ + +The mailing list email is ``openstack@lists.launchpad.net``. This is a common +mailing list across the OpenStack projects. To participate in the mailing list: + +#. Join the `Nova Team`_ on Launchpad. +#. Subscribe to the list on the `OpenStack Team`_ page on Launchpad. + +The mailing list archives are at https://lists.launchpad.net/openstack. + + +Bug tracking +------------ + +Report Nova bugs at https://bugs.launchpad.net/nova + +Feature requests (Blueprints) +----------------------------- + +Nova uses Launchpad Blueprints to track feature requests. Blueprints are at +https://blueprints.launchpad.net/nova. + +Technical support (Answers) +--------------------------- + +Nova uses Launchpad Answers to track Nova technical support questions. The Nova +Answers page is at https://answers.launchpad.net/nova. + +Note that the `OpenStack Forums`_ (which are not hosted on Launchpad) can also +be used for technical support requests. + +.. _Launchpad: http://launchpad.net +.. _Wiki: http://wiki.openstack.org +.. _Nova Team: https://launchpad.net/~nova +.. _OpenStack Team: https://launchpad.net/~openstack +.. _OpenStack Forums: http://forums.openstack.org/ \ No newline at end of file diff --git a/doc/source/devref/unit_tests.rst b/doc/source/devref/unit_tests.rst new file mode 100644 index 000000000000..f8ce7e7555d5 --- /dev/null +++ b/doc/source/devref/unit_tests.rst @@ -0,0 +1,143 @@ +Unit Tests +========== + +Nova contains a suite of unit tests, in the nova/tests directory. + +Any proposed code change will be automatically rejected by the OpenStack +Jenkins server [#f1]_ if the change causes unit test failures. + +Running the tests +----------------- +Run the unit tests by doing:: + + ./run_tests.sh + +This script is a wrapper around the `nose`_ testrunner and the `pep8`_ checker. + +.. _nose: http://code.google.com/p/python-nose/ +.. _pep8: https://github.com/jcrocholl/pep8 + +Flags +----- + +The ``run_tests.sh`` script supports several flags. You can view a list of +flags by doing:: + + run_tests.sh -h + +This will show the following help information:: + + Usage: ./run_tests.sh [OPTION]... + Run Nova's test suite(s) + + -V, --virtual-env Always use virtualenv. Install automatically if not present + -N, --no-virtual-env Don't use virtualenv. Run tests in local environment + -s, --no-site-packages Isolate the virtualenv from the global Python environment + -r, --recreate-db Recreate the test database (deprecated, as this is now the default). + -n, --no-recreate-db Don't recreate the test database. + -x, --stop Stop running tests after the first error or failure. + -f, --force Force a clean re-build of the virtual environment. Useful when dependencies have been added. + -p, --pep8 Just run pep8 + -P, --no-pep8 Don't run pep8 + -c, --coverage Generate coverage report + -h, --help Print this usage message + --hide-elapsed Don't print the elapsed time for each test along with slow test list + +Because ``run_tests.sh`` is a wrapper around nose, it also accepts the same +flags as nosetests. See the `nose options documentation`_ for details about +these additional flags. + +.. _nose options documentation: http://readthedocs.org/docs/nose/en/latest/usage.html#options + +Running a subset of tests +------------------------- + +Instead of running all tests, you can specify an individual directory, file, +class, or method that contains test code. + +To run the tests in the ``nova/tests/scheduler`` directory:: + + ./run_tests.sh scheduler + +To run the tests in the ``nova/tests/test_libvirt.py`` file:: + + ./run_tests.sh test_libvirt + +To run the tests in the `HostStateTestCase` class in +``nova/tests/test_libvirt.py``:: + + ./run_tests.sh test_libvirt:HostStateTestCase + +To run the `ToPrimitiveTestCase.test_dict` test method in +``nova/tests/test_utils.py``:: + + ./run_tests.sh test_utils:ToPrimitiveTestCase.test_dict + + +Suppressing logging output when tests fail +------------------------------------------ + +By default, when one or more unit test fails, all of the data sent to the +logger during the failed tests will appear on standard output, which typically +consists of many lines of texts. The logging output can make it difficult to +identify which specific tests have failed, unless your terminal has a large +scrollback buffer or you have redirected output to a file. + +You can suppress the logging output by calling ``run_tests.sh`` with the nose +flag:: + + --nologcapture + +Virtualenv +---------- + +By default, the tests use the Python packages installed inside a +virtualenv [#f2]_. (This is equivalent to using the ``-V, --virtualenv`` flag). +If the virtualenv does not exist, it will be created the first time the tests are run. + +If you wish to recreate the virtualenv, call ``run_tests.sh`` with the flag:: + + -f, --force + +Recreating the virtualenv is useful if the package dependencies have changed +since the virtualenv was last created. If the ``tools/pip-requires`` or +``tools/install_venv.py`` files have changed, it's a good idea to recreate the +virtualenv. + +By default, the unit tests will see both the packages in the virtualenv and +the packages that have been installed in the Python global environment. In +some cases, the packages in the Python global environment may cause a conflict +with the packages in the virtualenv. If this occurs, you can isolate the +virtualenv from the global environment by using the flag:: + + -s, --no-site packages + +If you do not wish to use a virtualenv at all, use the flag:: + + -N, --no-virtual-env + +Database +-------- + +Some of the unit tests make queries against an sqlite database [#f3]_. By +default, the test database (``tests.sqlite``) is deleted and recreated each +time ``run_tests.sh`` is invoked (This is equivalent to using the +``-r, --recreate-db`` flag). To reduce testing time if a database already +exists it can be reused by using the flag:: + + -n, --no-recreate-db + +Reusing an existing database may cause tests to fail if the schema has +changed. If any files in the ``nova/db/sqlalchemy`` have changed, it's a good +idea to recreate the test database. + + +.. rubric:: Footnotes + +.. [#f1] See :doc:`jenkins`. + +.. [#f2] See :doc:`development.environment` for more details about the use of + virtualenv. + +.. [#f3] There is an effort underway to use a fake DB implementation for the + unit tests. See https://lists.launchpad.net/openstack/msg05604.html