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:
Lorin Hochstein
parent
efc639ff4e
commit
40f39557b3
|
|
@ -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 <http://wiki.openstack.org/CLA>`_. 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 <http://wiki.openstack.org/CLA>`_. 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 `<irc://freenode.net/#openstack>`_. 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
|
||||
`<http://eavesdrop.openstack.org/irclogs/>`_.
|
||||
|
||||
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 <http://wiki.openstack.org/>`_
|
||||
* `OpenStack Wiki <http://wiki.openstack.org/>`_
|
||||
|
||||
|
||||
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 <http://github.com/openstack/nova>`_
|
||||
|
||||
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>`_
|
||||
|
||||
|
|
|
|||
|
|
@ -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`<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
|
||||
--------------------
|
||||
|
||||
|
|
@ -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
|
||||
--------------------------------------------
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
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
|
||||
-------------
|
||||
|
|
|
|||
|
|
@ -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/
|
||||
|
|
@ -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/
|
||||
|
|
@ -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