@@ -25,23 +25,63 @@ __ contribute_

 __ lp_

 .. _lp: https://launchpad.net/~devstack

+The `Gerrit review

+queue <https://review.openstack.org/#/q/project:openstack-dev/devstack,n,z>`__

+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 <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.  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

deleted file mode 100644

@@ -1,94 +0,0 @@

-============

-Contributing

-============

-

-DevStack uses the standard OpenStack contribution process as outlined in

-`the OpenStack developer

-guide <http://docs.openstack.org/infra/manual/developers.html>`__. 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.

new file mode 100644

@@ -0,0 +1 @@

+.. include:: ../../HACKING.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 <contributing>`

+:doc:`Pitching in to make DevStack a better place <hacking>`

 Code

 ====