Fix typos and thinkos in docs
Updates for the new major features and some clarification
Partial-Bug: #1235626
Change-Id: If2da63e62a14894e498b4163b5052d9b2b2069ed
diff --git a/HACKING.rst b/HACKING.rst
index 5f33d77..3c08e67 100644
--- a/HACKING.rst
+++ b/HACKING.rst
@@ -5,10 +5,10 @@
General
-------
-DevStack is written in POSIX shell script. This choice was made because
-it best illustrates the configuration steps that this implementation takes
-on setting up and interacting with OpenStack components. DevStack specifically
-uses Bash and is compatible with Bash 3.
+DevStack is written in UNIX shell script. It uses a number of bash-isms
+and so is limited to Bash (version 3 and up) and compatible shells.
+Shell script was chosen because it best illustrates the steps used to
+set up and interact with OpenStack components.
DevStack's official repository is located on GitHub at
https://github.com/openstack-dev/devstack.git. Besides the master branch that
@@ -54,14 +54,14 @@
``TOP_DIR`` should always point there, even if the script itself is located in
a subdirectory::
- # Keep track of the current devstack directory.
+ # Keep track of the current DevStack directory.
TOP_DIR=$(cd $(dirname "$0") && pwd)
Many scripts will utilize shared functions from the ``functions`` file. There are
also rc files (``stackrc`` and ``openrc``) that are often included to set the primary
configuration of the user environment::
- # Keep track of the current devstack directory.
+ # Keep track of the current DevStack directory.
TOP_DIR=$(cd $(dirname "$0") && pwd)
# Import common functions
@@ -100,13 +100,14 @@
-------
``stackrc`` is the global configuration file for DevStack. It is responsible for
-calling ``localrc`` if it exists so configuration can be overridden by the user.
+calling ``local.conf`` (or ``localrc`` if it exists) so local user configuration
+is recognized.
The criteria for what belongs in ``stackrc`` can be vaguely summarized as
follows:
-* All project respositories and branches (for historical reasons)
-* Global configuration that may be referenced in ``localrc``, i.e. ``DEST``, ``DATA_DIR``
+* All project repositories and branches handled directly in ``stack.sh``
+* Global configuration that may be referenced in ``local.conf``, i.e. ``DEST``, ``DATA_DIR``
* Global service configuration like ``ENABLED_SERVICES``
* Variables used by multiple services that do not have a clear owner, i.e.
``VOLUME_BACKING_FILE_SIZE`` (nova-volumes and cinder) or ``PUBLIC_NETWORK_NAME``
@@ -116,8 +117,9 @@
not be changed for other reasons but the earlier file needs to dereference a
variable set in the later file. This should be rare.
-Also, variable declarations in ``stackrc`` do NOT allow overriding (the form
-``FOO=${FOO:-baz}``); if they did then they can already be changed in ``localrc``
+Also, variable declarations in ``stackrc`` before ``local.conf`` is sourced
+do NOT allow overriding (the form
+``FOO=${FOO:-baz}``); if they did then they can already be changed in ``local.conf``
and can stay in the project file.
@@ -139,7 +141,9 @@
Markdown formatting in the comments; use it sparingly. Specifically, ``stack.sh``
uses Markdown headers to divide the script into logical sections.
-.. _shocco: http://rtomayko.github.com/shocco/
+.. _shocco: https://github.com/dtroyer/shocco/tree/rst_support
+
+The script used to drive <code>shocco</code> is <code>tools/build_docs.sh</code>.
Exercises