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
This commit is contained in:
parent
efc639ff4e
commit
40f39557b3
@ -54,7 +54,7 @@ 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
|
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.
|
to write drafts for specs or documentation, describe a blueprint, or collaborate with others.
|
||||||
|
|
||||||
`OpenStack Wiki <http://wiki.openstack.org/>`_
|
* `OpenStack Wiki <http://wiki.openstack.org/>`_
|
||||||
|
|
||||||
|
|
||||||
Nova on Github
|
Nova on Github
|
||||||
@ -67,6 +67,7 @@ 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 <http://launchpad.net/nova>`_
|
* `Launchpad Nova Page <http://launchpad.net/nova>`_
|
||||||
|
|
||||||
|
@ -19,10 +19,18 @@ Setting Up a Development Environment
|
|||||||
====================================
|
====================================
|
||||||
|
|
||||||
This page describes how to setup a working Python development environment that
|
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
|
can be used in developing nova on Ubuntu, Fedora or Mac OS X. These
|
||||||
instructions assume you're already familiar with git. Refer to
|
instructions assume you're already familiar with git. Refer to
|
||||||
http://wiki.openstack.org/GettingTheCode for additional information.
|
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`<http://wiki.openstack.org/HypervisorSupportMatrix>_. 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
|
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
|
sudo yum install python-devel swig openssl-devel python-pip git
|
||||||
|
|
||||||
|
|
||||||
Mac OS X Systems
|
Mac OS X Systems
|
||||||
----------------
|
----------------
|
||||||
|
|
||||||
@ -97,6 +106,9 @@ environment (hit "y")::
|
|||||||
|
|
||||||
No virtual environment found...create one? (Y/n)
|
No virtual environment found...create one? (Y/n)
|
||||||
|
|
||||||
|
See :doc:`unit_tests` for more details.
|
||||||
|
|
||||||
|
.. _virtualenv:
|
||||||
|
|
||||||
Manually installing and using the virtualenv
|
Manually installing and using the virtualenv
|
||||||
--------------------------------------------
|
--------------------------------------------
|
||||||
|
16
doc/source/devref/gerrit.rst
Normal file
16
doc/source/devref/gerrit.rst
Normal file
@ -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
|
@ -27,6 +27,7 @@ Programming HowTos and Tutorials
|
|||||||
:maxdepth: 3
|
:maxdepth: 3
|
||||||
|
|
||||||
development.environment
|
development.environment
|
||||||
|
unit_tests
|
||||||
addmethod.openstackapi
|
addmethod.openstackapi
|
||||||
|
|
||||||
|
|
||||||
@ -42,6 +43,14 @@ Background Concepts for Nova
|
|||||||
zone
|
zone
|
||||||
rabbit
|
rabbit
|
||||||
|
|
||||||
|
Other Resources
|
||||||
|
---------------
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 3
|
||||||
|
|
||||||
|
launchpad
|
||||||
|
gerrit
|
||||||
|
jenkins
|
||||||
|
|
||||||
API Reference
|
API Reference
|
||||||
-------------
|
-------------
|
||||||
|
36
doc/source/devref/jenkins.rst
Normal file
36
doc/source/devref/jenkins.rst
Normal file
@ -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 <http://www.logilab.org/project/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/
|
54
doc/source/devref/launchpad.rst
Normal file
54
doc/source/devref/launchpad.rst
Normal file
@ -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/
|
143
doc/source/devref/unit_tests.rst
Normal file
143
doc/source/devref/unit_tests.rst
Normal file
@ -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
|
Loading…
Reference in New Issue
Block a user