devstack/doc/source/contributing.rst

Contributing

DevStack uses the standard OpenStack contribution process as outlined in the OpenStack developer guide. This means that you will need to meet the requirements of the Contribututors License Agreement (CLA). If you have already done that for another OpenStack project you are good to go.

Things To Know

Where Things Are

The official DevStack repository is located at git://git.openstack.org/openstack-dev/devstack.git, replicated from the repo maintained by Gerrit. GitHub also has a mirror at git://github.com/openstack-dev/devstack.git.

The blueprint and bug trackers are on Launchpad. It should be noted that DevStack generally does not use these as strongly as other projects, but we're trying to change that.

The Gerrit review queue is, however, used for all commits except for the text of this website. That should also change in the near future.

HACKING.rst

Like most OpenStack projects, DevStack includes a HACKING.rst file that describes the layout, style and conventions of the project. Because HACKING.rst is in the main DevStack repo it is considered authoritative. Much of the content on this page is taken from there.

bashate Formatting

Around the time of the OpenStack Havana release we added a tool to do style checking in DevStack similar to what pep8/flake8 do for Python projects. It is still _very_ simplistic, focusing mostly on stray whitespace to help prevent -1 on reviews that are otherwise acceptable. Oddly enough it is called bashate. It will be expanded to enforce some of the documentation rules in comments that are used in formatting the script pages for devstack.org and possibly even simple code formatting. Run it on the entire project with ./run_tests.sh.

Code

Repo Layout

The DevStack repo generally keeps all of the primary scripts at the root level.

doc - Contains the Sphinx source for the documentation. tools/build_docs.sh is used to generate the HTML versions of the DevStack scripts. A complete doc build can be run with tox -edocs.

exercises - Contains the test scripts used to sanity-check and demonstrate some OpenStack functions. These scripts know how to exit early or skip services that are not enabled.

extras.d - Contains the dispatch scripts called by the hooks in stack.sh, unstack.sh and clean.sh. See the plugins docs <plugins> for more information.

files - Contains a variety of otherwise lost files used in configuring and operating DevStack. This includes templates for configuration files and the system dependency information. This is also where image files are downloaded and expanded if necessary.

lib - Contains the sub-scripts specific to each project. This is where the work of managing a project's services is located. Each top-level project (Keystone, Nova, etc) has a file here. Additionally there are some for system services and project plugins.

samples - Contains a sample of the local files not included in the DevStack repo.

tests - the DevStack test suite is rather sparse, mostly consisting of test of specific fragile functions in the functions and functions-common files.

tools - Contains a collection of stand-alone scripts. While these may reference the top-level DevStack configuration they can generally be run alone. There are also some sub-directories to support specific environments such as XenServer.