Development Guidelines¶

Coding Guidelines¶

For the most part we try to follow PEP 8 guidelines which can be viewed here: http://www.python.org/dev/peps/pep-0008/

Testing Guidelines¶

Swift has a comprehensive suite of tests and pep8 checks that are run on all submitted code, and it is recommended that developers execute the tests 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/

To execute the tests:

• 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
  

• Install tox:

  pip install tox
  

• Generate list of distribution packages to install for testing:

  tox -e bindep
  

  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:

  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 environment variable. For example, to run only the pep8 checks and python2.7 unit tests use:

  tox -e pep8,py27
  

  or:

  TOXENV=py27,pep8 tox
  

Swift’s functional tests may be executed against a SAIO - Swift All In One or other running Swift cluster using the command:

tox -e func

The endpoint and authorization credentials to be used by functional tests should be configured in the test.conf file as described in the section Setting up scripts for running Swift.

The environment variable SWIFT_TEST_POLICY may be set to specify a particular storage policy name that will be used for testing. When set, tests that would otherwise not specify a policy or choose a random policy from those available will instead use the policy specified. Tests that use more than one policy will include the specified policy in the set of policies used. The specified policy must be available on the cluster under test.

For example, this command would run the functional tests using policy ‘silver’:

SWIFT_TEST_POLICY=silver tox -e func

To run a single functional test, use the --no-discover option together with a path to a specific test method, for example:

tox -e func -- --no-discover test.functional.tests.TestFile.testCopy

SWIFT_TEST_IN_PROCESS=1 SWIFT_TEST_IN_PROCESS_CONF_LOADER=encryption \
    tox -e func

tox -e func-encryption

tox -e func-ec

SWIFT_TEST_IN_PROCESS=1 tox -e func -- --pdb \
    test.functional.tests.TestFile.testCopy

SWIFT_TEST_IN_PROCESS_CONF_DIR=<custom_conf_source_dir>

SWIFT_TEST_IN_PROCESS=1 SWIFT_TEST_IN_PROCESS_CONF_DIR=$HOME/my_tests \
   SWIFT_TEST_POLICY=silver tox -e func

Coding Style¶

Swift uses flake8 with the OpenStack hacking module to enforce coding style.

Install flake8 and hacking with pip or by the packages of your Operating System.

It is advised to integrate flake8+hacking with your editor to get it automated and not get caught by Jenkins.

For example for Vim the syntastic plugin can do this for you.

Documentation Guidelines¶

The documentation in docstrings should follow the PEP 257 conventions (as mentioned in the PEP 8 guidelines).

More specifically:

1. Triple quotes should be used for all docstrings.
2. If the docstring is simple and fits on one line, then just use one line.
3. For docstrings that take multiple lines, there should be a newline after the opening quotes, and before the closing quotes.
4. Sphinx is used to build documentation, so use the restructured text markup to designate parameters, return values, etc. Documentation on the sphinx specific markup can be found here: http://sphinx.pocoo.org/markup/index.html

To build documentation run:

pip install -r requirements.txt -r doc/requirements.txt
sphinx-build -W -b html doc/source doc/build/html

and then browse to doc/build/html/index.html. These docs are auto-generated after every commit and available online at https://docs.openstack.org/swift/latest/.

Manpages¶

For sanity check of your change in manpage, use this command in the root of your Swift repo:

./.manpages

License and Copyright¶

You can have the following copyright and license statement at the top of each source file. Copyright assignment is optional.

New files should contain the current year. Substantial updates can have another year added, and date ranges are not needed.:

# Copyright (c) 2013 OpenStack Foundation.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
# implied.
# See the License for the specific language governing permissions and
# limitations under the License.