2010-05-28 06:05:26 +00:00
|
|
|
Nova Style Commandments
|
|
|
|
=======================
|
|
|
|
|
2013-07-01 12:58:44 +00:00
|
|
|
- Step 1: Read the OpenStack Style Commandments
|
2018-02-07 11:20:07 +00:00
|
|
|
https://docs.openstack.org/hacking/latest/
|
2013-07-01 12:58:44 +00:00
|
|
|
- Step 2: Read on
|
2010-05-28 06:05:26 +00:00
|
|
|
|
2013-07-01 12:58:44 +00:00
|
|
|
Nova Specific Commandments
|
|
|
|
---------------------------
|
2011-07-29 16:49:48 +00:00
|
|
|
|
2013-07-01 12:58:44 +00:00
|
|
|
- ``nova.db`` imports are not allowed in ``nova/virt/*``
|
2013-06-22 19:05:46 +00:00
|
|
|
- [N309] no db session in public API methods (disabled)
|
2014-06-21 10:56:42 +00:00
|
|
|
This enforces a guideline defined in ``oslo.db.sqlalchemy.session``
|
2013-07-11 08:52:52 +00:00
|
|
|
- [N310] timeutils.utcnow() wrapper must be used instead of direct calls to
|
|
|
|
datetime.datetime.utcnow() to make it easy to override its return value in tests
|
2013-12-17 17:20:48 +00:00
|
|
|
- [N311] importing code from other virt drivers forbidden
|
|
|
|
Code that needs to be shared between virt drivers should be moved
|
|
|
|
into a common module
|
|
|
|
- [N312] using config vars from other virt drivers forbidden
|
|
|
|
Config parameters that need to be shared between virt drivers
|
|
|
|
should be moved into a common module
|
2014-02-06 12:06:48 +00:00
|
|
|
- [N313] capitalize help string
|
|
|
|
Config parameter help strings should have a capitalized first letter
|
2014-01-17 13:52:25 +00:00
|
|
|
- [N316] Change assertTrue(isinstance(A, B)) by optimal assert like
|
|
|
|
assertIsInstance(A, B).
|
|
|
|
- [N317] Change assertEqual(type(A), B) by optimal assert like
|
|
|
|
assertIsInstance(A, B)
|
2014-04-27 12:03:33 +00:00
|
|
|
- [N319] Validate that debug level logs are not translated.
|
2014-06-03 05:12:56 +00:00
|
|
|
- [N320] Setting CONF.* attributes directly in tests is forbidden. Use
|
|
|
|
self.flags(option=value) instead.
|
2014-03-02 08:04:24 +00:00
|
|
|
- [N321] Validate that LOG messages, except debug ones, have translations
|
2014-06-07 02:49:20 +00:00
|
|
|
- [N322] Method's default argument shouldn't be mutable
|
2014-07-29 19:58:24 +00:00
|
|
|
- [N323] Ensure that the _() function is explicitly imported to ensure proper translations.
|
2014-08-14 10:40:09 +00:00
|
|
|
- [N324] Ensure that jsonutils.%(fun)s must be used instead of json.%(fun)s
|
2014-10-17 20:14:26 +00:00
|
|
|
- [N325] str() and unicode() cannot be used on an exception. Remove use or use six.text_type()
|
2014-08-21 03:57:30 +00:00
|
|
|
- [N326] Translated messages cannot be concatenated. String should be included in translated message.
|
2016-06-13 06:30:59 +00:00
|
|
|
- [N327] Do not use xrange(). xrange() is not compatible with Python 3. Use range() or six.moves.range() instead.
|
2014-09-18 10:08:37 +00:00
|
|
|
- [N328] Validate that LOG.info messages use _LI.
|
2014-09-22 12:39:12 +00:00
|
|
|
- [N329] Validate that LOG.exception messages use _LE.
|
2015-02-05 06:58:46 +00:00
|
|
|
- [N330] Validate that LOG.warning and LOG.warn messages use _LW.
|
2014-12-02 10:43:16 +00:00
|
|
|
- [N332] Check that the api_version decorator is the first decorator on a method
|
2014-11-26 07:56:24 +00:00
|
|
|
- [N334] Change assertTrue/False(A in/not in B, message) to the more specific
|
|
|
|
assertIn/NotIn(A, B, message)
|
2015-01-08 16:38:28 +00:00
|
|
|
- [N335] Check for usage of deprecated assertRaisesRegexp
|
2014-12-24 10:10:30 +00:00
|
|
|
- [N336] Must use a dict comprehension instead of a dict constructor with a sequence of key-value pairs.
|
2014-11-18 13:19:31 +00:00
|
|
|
- [N337] Don't import translation in tests
|
2014-10-23 12:32:33 +00:00
|
|
|
- [N338] Change assertEqual(A in B, True), assertEqual(True, A in B),
|
|
|
|
assertEqual(A in B, False) or assertEqual(False, A in B) to the more specific
|
|
|
|
assertIn/NotIn(A, B)
|
2015-03-09 02:19:32 +00:00
|
|
|
- [N339] Check common raise_feature_not_supported() is used for v2.1 HTTPNotImplemented response.
|
2015-06-25 14:41:49 +00:00
|
|
|
- [N340] Check nova.utils.spawn() is used instead of greenthread.spawn() and eventlet.spawn()
|
2015-09-29 01:46:51 +00:00
|
|
|
- [N341] contextlib.nested is deprecated
|
2015-11-24 16:37:13 +00:00
|
|
|
- [N342] Config options should be in the central location ``nova/conf/``
|
2015-11-24 13:03:50 +00:00
|
|
|
- [N343] Check for common double word typos
|
2016-01-15 08:30:56 +00:00
|
|
|
- [N344] Python 3: do not use dict.iteritems.
|
|
|
|
- [N345] Python 3: do not use dict.iterkeys.
|
|
|
|
- [N346] Python 3: do not use dict.itervalues.
|
2016-02-17 23:07:16 +00:00
|
|
|
- [N348] Deprecated library function os.popen()
|
2016-02-25 20:23:12 +00:00
|
|
|
- [N349] Check for closures in tests which are not used
|
2016-07-01 15:30:58 +00:00
|
|
|
- [N350] Policy registration should be in the central location ``nova/policies/``
|
2016-07-01 17:51:48 +00:00
|
|
|
- [N351] Do not use the oslo_policy.policy.Enforcer.enforce() method.
|
2016-07-16 12:20:48 +00:00
|
|
|
- [N352] LOG.warn is deprecated. Enforce use of LOG.warning.
|
2016-05-16 22:09:44 +00:00
|
|
|
- [N353] Validate that context objects is not passed in logging calls.
|
2016-08-31 13:45:51 +00:00
|
|
|
- [N355] Enforce use of assertTrue/assertFalse
|
|
|
|
- [N356] Enforce use of assertIs/assertIsNot
|
2016-09-29 14:29:03 +00:00
|
|
|
- [N357] Use oslo_utils.uuidutils or uuidsentinel(in case of test cases) to
|
|
|
|
generate UUID instead of uuid4().
|
2016-09-15 05:53:52 +00:00
|
|
|
- [N358] Return must always be followed by a space when returning a value.
|
2018-02-13 16:29:58 +00:00
|
|
|
- [N359] Check for redundant import aliases.
|
2018-03-07 05:45:42 +00:00
|
|
|
- [N360] Yield must always be followed by a space when yielding a value.
|
2018-10-25 02:24:09 +00:00
|
|
|
- [N361] Check for usage of deprecated assertRegexpMatches and
|
|
|
|
assertNotRegexpMatches
|
2013-05-17 22:18:18 +00:00
|
|
|
|
2011-11-22 03:59:50 +00:00
|
|
|
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.
|
|
|
|
|
|
|
|
For more information on creating unit tests and utilizing the testing
|
2015-01-23 13:14:03 +00:00
|
|
|
infrastructure in OpenStack Nova, please read ``nova/tests/unit/README.rst``.
|
2013-02-11 21:22:24 +00:00
|
|
|
|
|
|
|
|
|
|
|
Running Tests
|
|
|
|
-------------
|
2017-11-13 22:13:18 +00:00
|
|
|
The testing system is based on a combination of tox and stestr. The canonical
|
2013-07-01 12:58:44 +00:00
|
|
|
approach to running tests is to simply run the command ``tox``. This will
|
|
|
|
create virtual environments, populate them with dependencies and run all of
|
2013-02-11 21:22:24 +00:00
|
|
|
the tests that OpenStack CI systems run. Behind the scenes, tox is running
|
2017-11-13 22:13:18 +00:00
|
|
|
``stestr run``, but is set up such that you can supply any additional
|
|
|
|
stestr arguments that are needed to tox. For example, you can run:
|
|
|
|
``tox -- --analyze-isolation`` to cause tox to tell stestr to add
|
2013-02-11 21:22:24 +00:00
|
|
|
--analyze-isolation to its argument list.
|
|
|
|
|
2014-05-15 22:05:03 +00:00
|
|
|
Python packages may also have dependencies that are outside of tox's ability
|
2017-11-13 22:13:18 +00:00
|
|
|
to install. Please refer to `Development Quickstart`_ for
|
2014-05-15 22:05:03 +00:00
|
|
|
a list of those packages on Ubuntu, Fedora and Mac OS X.
|
|
|
|
|
2014-10-31 09:14:59 +00:00
|
|
|
To run a single or restricted set of tests, pass a regex that matches
|
|
|
|
the class name containing the tests as an extra ``tox`` argument;
|
|
|
|
e.g. ``tox -- TestWSGIServer`` (note the double-hypen) will test all
|
2015-07-14 18:56:45 +00:00
|
|
|
WSGI server tests from ``nova/tests/unit/test_wsgi.py``; ``--
|
2014-10-31 09:14:59 +00:00
|
|
|
TestWSGIServer.test_uri_length_limit`` would run just that test, and
|
|
|
|
``-- TestWSGIServer|TestWSGIServerWithSSL`` would run tests from both
|
|
|
|
classes.
|
|
|
|
|
2013-02-11 21:22:24 +00:00
|
|
|
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
|
2017-11-13 22:13:18 +00:00
|
|
|
installed locally already. In this case, you can interact with the stestr
|
|
|
|
command directly. Running ``stestr run`` will run the entire test suite.
|
|
|
|
``stestr run --concurrency=1`` will run tests serially (by default, stestr runs
|
|
|
|
tests in parallel). More information about stestr can be found at:
|
|
|
|
http://stestr.readthedocs.io/
|
|
|
|
|
2019-02-13 19:59:02 +00:00
|
|
|
By default tests log at ``INFO`` level. It is possible to make them
|
|
|
|
log at ``DEBUG`` level by exporting the ``OS_DEBUG`` environment
|
|
|
|
variable to ``True``.
|
|
|
|
|
2017-11-13 22:13:18 +00:00
|
|
|
.. _Development Quickstart: https://docs.openstack.org/nova/latest/contributor/development-environment.html
|
2012-02-03 00:50:58 +00:00
|
|
|
|
2013-05-31 12:41:39 +00:00
|
|
|
Building Docs
|
|
|
|
-------------
|
2013-07-01 12:58:44 +00:00
|
|
|
Normal Sphinx docs can be built via the setuptools ``build_sphinx`` command. To
|
2015-07-14 18:56:45 +00:00
|
|
|
do this via ``tox``, simply run ``tox -e docs``,
|
2013-05-31 12:41:39 +00:00
|
|
|
which will cause a virtualenv with all of the needed dependencies to be
|
|
|
|
created and then inside of the virtualenv, the docs will be created and
|
|
|
|
put into doc/build/html.
|
|
|
|
|
2015-07-07 22:32:59 +00:00
|
|
|
Building a PDF of the Documentation
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
If you'd like a PDF of the documentation, you'll need LaTeX and ImageMagick
|
|
|
|
installed, and additionally some fonts. On Ubuntu systems, you can get what you
|
|
|
|
need with::
|
2013-05-31 12:41:39 +00:00
|
|
|
|
2015-07-07 22:32:59 +00:00
|
|
|
apt-get install texlive-full imagemagick
|
2013-05-31 12:41:39 +00:00
|
|
|
|
2016-03-24 07:34:12 +00:00
|
|
|
Then you can use the ``build_latex_pdf.sh`` script in tools/ to take care
|
|
|
|
of both the sphinx latex generation and the latex compilation. For example::
|
2013-05-31 12:41:39 +00:00
|
|
|
|
2015-07-07 22:32:59 +00:00
|
|
|
tools/build_latex_pdf.sh
|
2013-05-31 12:41:39 +00:00
|
|
|
|
2015-07-07 22:32:59 +00:00
|
|
|
The script must be run from the root of the Nova repository and it'll copy the
|
|
|
|
output pdf to Nova.pdf in that directory.
|