Move contributing into HACKING
contributing.rst doesn't add very much over the extant HACKING.rst, so
move some of the unique bits into HACKING.rst and then link that into
the documentation.
Change-Id: I0530f38eda92f8dd374c0ec224556ace6e679f54
diff --git a/HACKING.rst b/HACKING.rst
index b3c82a3..4971db2 100644
--- a/HACKING.rst
+++ b/HACKING.rst
@@ -25,23 +25,63 @@
__ 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 @@
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 @@
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