From fc24a2322d213ac04364ae5c142a14376ca0d732 Mon Sep 17 00:00:00 2001 From: Alistair Coles Date: Thu, 24 Nov 2016 11:38:10 +0000 Subject: [PATCH] Add pip and virtualenv upgrade to development guidelines Change [1] requires pip >= 7.0.1. In general, test environments will need to have pip and virtualenv in line with global requirements. Add a reference to the global requirements rather than specifying versions that will inevitably become stale. Also adds inline literal markup to all occurences of "tox" for consistency. [1] Related-Change: I7c60be623b4340ee34ae1aa520f17b303348811d Change-Id: I7730f22c594a3521973cb9ff264a7d50f2b86a1a Depends-On: I45eee626713438af5fc676f2b5f636d7ec23f7be --- doc/source/development_guidelines.rst | 32 +++++++++++++++++---------- 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/doc/source/development_guidelines.rst b/doc/source/development_guidelines.rst index 17e4aed984..8fbda2b0c1 100644 --- a/doc/source/development_guidelines.rst +++ b/doc/source/development_guidelines.rst @@ -19,11 +19,19 @@ themselves to catch regressions early. Developers are also expected to keep the test suite up-to-date with any submitted code changes. Swift's tests and pep8 checks can be executed in an isolated environment -with Tox: http://tox.testrun.org/ +with ``tox``: http://tox.testrun.org/ To execute the tests: -* Install Tox:: +* Ensure ``pip`` and ``virtualenv`` are upgraded to satisfy the version + requirements listed in the OpenStack `global requirements`_:: + + pip install pip -U + pip install virtualenv -U + +.. _`global requirements`: https://github.com/openstack/requirements/blob/master/global-requirements.txt + +* Install ``tox``:: pip install tox @@ -34,18 +42,18 @@ To execute the tests: Now install these packages using your distribution package manager like apt-get, dnf, yum, or zypper. -* Run Tox from the root of the swift repo:: +* Run ``tox`` from the root of the swift repo:: tox - Remarks: +.. note:: If you installed using ``cd ~/swift; sudo python setup.py develop``, you may need to do ``cd ~/swift; sudo chown -R ${USER}:${USER} swift.egg-info`` prior - to running tox. + to running ``tox``. * By default ``tox`` will run all of the unit test and pep8 checks listed in the ``tox.ini`` file ``envlist`` option. A subset of the test environments - can be specified on the tox command line or by setting the ``TOXENV`` + can be specified on the ``tox`` command line or by setting the ``TOXENV`` environment variable. For example, to run only the pep8 checks and python2.7 unit tests use:: @@ -56,17 +64,17 @@ To execute the tests: TOXENV=py27,pep8 tox .. note:: - As of tox version 2.0.0, most environment variables are not automatically + As of ``tox`` version 2.0.0, most environment variables are not automatically passed to the test environment. Swift's ``tox.ini`` overrides this default behavior so that variable names matching ``SWIFT_*`` and ``*_proxy`` will be passed, but you may need to run ``tox --recreate`` for this to take effect - after upgrading from tox<2.0.0. + after upgrading from ``tox`` <2.0.0. Conversely, if you do not want those environment variables to be passed to the test environment then you will need to unset them before calling ``tox``. Also, if you ever encounter DistributionNotFound, try to use ``tox - --recreate`` or remove the ``.tox`` directory to force tox to recreate the + --recreate`` or remove the ``.tox`` directory to force ``tox`` to recreate the dependency list. Swift's functional tests may be executed against a :doc:`development_saio` or @@ -103,7 +111,7 @@ If the ``test.conf`` file is not found then the functional test framework will instantiate a set of Swift servers in the same process that executes the functional tests. This 'in-process test' mode may also be enabled (or disabled) by setting the environment variable ``SWIFT_TEST_IN_PROCESS`` to a true (or -false) value prior to executing `tox -e func`. +false) value prior to executing ``tox -e func``. When using the 'in-process test' mode some server configuration options may be set using environment variables: @@ -113,7 +121,7 @@ set using environment variables: - encryption may be added to the proxy pipeline by setting the environment variable ``SWIFT_TEST_IN_PROCESS_CONF_LOADER`` to - ``encryption``. Or when using tox, specify the tox environment + ``encryption``. Or when using ``tox``, specify the ``tox`` environment ``func-in-process-encryption`` - the proxy-server ``object_post_as_copy`` option may be set using the @@ -133,7 +141,7 @@ tox environment:: tox -e func-in-process-fast-post To debug the functional tests, use the 'in-process test' mode and pass the -``--pdb`` flag to tox:: +``--pdb`` flag to ``tox``:: SWIFT_TEST_IN_PROCESS=1 tox -e func -- --pdb \ test.functional.tests.TestFile.testCopy