3293046d30
While rst doesn't actually care about the order of headers, reviewers sometimes do. And the build in emacs mode has a certain order specified that it can easily rotate between. Standardize on == h1, = h2, - h3, ~ h4 in the code. Change-Id: I80ff6df6ef0703a3c3005809069428018bb355d4
95 lines
3.6 KiB
ReStructuredText
95 lines
3.6 KiB
ReStructuredText
============
|
|
Contributing
|
|
============
|
|
|
|
DevStack uses the standard OpenStack contribution process as outlined in
|
|
`the OpenStack wiki 'How To
|
|
Contribute' <https://wiki.openstack.org/wiki/How_To_Contribute>`__. 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 <https://blueprints.launchpad.net/devstack>`__ and `bug
|
|
trackers <https://bugs.launchpad.net/devstack>`__ 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 <https://review.openstack.org/#/q/project:openstack-dev/devstack,n,z>`__
|
|
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 :doc:`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.
|