diff --git a/HACKING.rst b/HACKING.rst index b3c82a37a8..4971db250b 100644 --- a/HACKING.rst +++ b/HACKING.rst @@ -25,23 +25,63 @@ __ contribute_ __ lp_ .. _lp: https://launchpad.net/~devstack +The `Gerrit review +queue `__ +is used for all commits. + The primary script in DevStack is ``stack.sh``, which performs the bulk of the work for DevStack's use cases. There is a subscript ``functions`` that contains generally useful shell functions and is used by a number of the scripts in DevStack. -The ``lib`` directory contains sub-scripts for projects or packages that ``stack.sh`` -sources to perform much of the work related to those projects. These sub-scripts -contain configuration defaults and functions to configure, start and stop the project -or package. These variables and functions are also used by related projects, -such as Grenade, to manage a DevStack installation. - A number of additional scripts can be found in the ``tools`` directory that may be useful in supporting DevStack installations. Of particular note are ``info.sh`` to collect and report information about the installed system, and ``install_prereqs.sh`` that handles installation of the prerequisite packages for DevStack. It is suitable, for example, to pre-load a system for making a snapshot. +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 ` 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. These +variables and functions are also used by related projects, such as +Grenade, to manage a DevStack installation. + +``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. + Scripts ------- @@ -249,6 +289,7 @@ Whitespace Rules Control Structure Rules ----------------------- + - then should be on the same line as the if - do should be on the same line as the for @@ -270,6 +311,7 @@ Example:: Variables and Functions ----------------------- + - functions should be used whenever possible for clarity - functions should use ``local`` variables as much as possible to ensure they are isolated from the rest of the environment diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst deleted file mode 100644 index 50c0100578..0000000000 --- a/doc/source/contributing.rst +++ /dev/null @@ -1,94 +0,0 @@ -============ -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 :doc:`the plugins -docs ` 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. diff --git a/doc/source/hacking.rst b/doc/source/hacking.rst new file mode 100644 index 0000000000..a2bcf4fd67 --- /dev/null +++ b/doc/source/hacking.rst @@ -0,0 +1 @@ +.. include:: ../../HACKING.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index bac593de03..0ffb15c2a8 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -12,7 +12,7 @@ DevStack - an OpenStack Community Production plugins faq changes - contributing + hacking Quick Start ----------- @@ -139,7 +139,7 @@ FAQ Contributing ------------ -:doc:`Pitching in to make DevStack a better place ` +:doc:`Pitching in to make DevStack a better place ` Code ====