Docs: Add developer guide for security role

This patch adds detailed instructions for developers who are working on
the security role. The patch also adds CentOS/RHEL 7 support to the
run_tests.sh script.

Change-Id: I0ab79f1e4abdb3deeca9b48da3b9e4f42be37980

doc/source/developer-guide.rst

@@ -0,0 +1,67 @@
+.. include:: <xhtml1-lat1.txt>
+`Home <index.html>`__ |raquo| Security hardening for openstack-ansible
+
+Developer Guide
+===============
+
+Building a development environment
+----------------------------------
+
+The OpenStack gate runs the tox tests found within ``tox.ini``. Developers
+should use these tox tests to verify that their changes will work when the gate
+jobs run. Some systems may need additional packages for these tests to run
+properly.
+
+To install all of the prerequisites and run the functional tests, use the
+``run_tests.sh`` script:
+
+.. code-block:: console
+
+    ./run_tests.sh
+
+.. note::
+
+   This script will apply the default security hardening configurations to the
+   local host. Avoid running this script on production servers which have not
+   been properly tested with the security role.
+
+Writing documentation
+---------------------
+
+Each security configuration has corresponding documentation found in
+``docs/source/developer-notes``. The documentation should be brief, but it must
+answer a few critical questions:
+
+* What does the change do to a system?
+* What is the value of making this change?
+* How can a deployer opt out or opt in for a particular change?
+* Is there additional documentation available online that may help a deployer
+  decide whether or not this change is valuable to them?
+
+Each developer note is stored with the configuration number as its filename.
+For example, the documentation for V-38476 is stored in
+``doc/source/developer-notes/V-38476.rst``. If the developer notes for several
+security configurations are identical, symbolic links can be used to avoid
+repeating information.
+
+Release notes
+-------------
+
+Adding release notes helps deployers and other developers discover the new
+additions to the role in a concise format. Release notes should be added to
+incoming patches if they would change something noticeable in the role, such as
+bug fixes, new functionality, or variable name changes.
+
+To add a release note, use ``reno``:
+
+.. code-block:: console
+
+    reno new i-made-a-new-feature-that-does-something-awesome
+
+Once you run the ``reno new`` command with a release note slug, a new file
+appears in ``releasenotes/notes``. Edit that file and adjust the relevant
+section to explain the changes found within your patch. Delete any unused
+sections and submit the release note with your patch.
+
+For more details, refer to the documentation on release notes found in the
+`OpenStack-Ansible developer documentation <http://docs.openstack.org/developer/openstack-ansible/developer-docs/contribute.html#release-notes>`_

doc/source/index.rst

@@ -37,8 +37,8 @@ in addition to the existing support for Ubuntu 14.04.
    benefits.rst
    configuration.rst
    getting-started.rst
-   writing-docs.rst
    controls.rst
+   developer-guide.rst
 
 Mitaka: Stable release
 ===================================================

doc/source/writing-docs.rst

@@ -1,12 +0,0 @@
-.. include:: <xhtml1-lat1.txt>
-`Home <index.html>`__ |raquo| Security hardening for openstack-ansible
-
-Writing documentation
-=====================
-
-The ``controls-cat[number].rst`` files are automatically generated with the
-``generate_docs.py`` script and the ``rhel6stig.csv``.
-
-Each hardening configuration does an import from the developer-notes directory
-and looks for a file called ``[STIG_ID].rst``.  As an example, the
-documentation for V-38476 would live in ``developer-notes/V-38476.rst``.

run_tests.sh

@@ -15,14 +15,19 @@
 
 set -euov
 
-FUNCTIONAL_TEST=${FUNCTIONAL_TEST:-false}
+FUNCTIONAL_TEST=${FUNCTIONAL_TEST:-true}
 
-# prep the host
+# Prepare Ubuntu 14.04 and 16.04 hosts
 if [ "$(which apt-get)" ]; then
   apt-get install -y build-essential python2.7 python-dev git-core libssl-dev libffi-dev
 fi
 
-# get pip, if necessary
+# Prepare CentOS and Red Hat Enterprise Linux 7 hosts
+if [ "$(which yum)" ]; then
+  yum -y install libffi-devel openssl-devel git python-devel "@Development Tools"
+fi
+
+# Download and install pip
 if [ ! "$(which pip)" ]; then
   curl --silent --show-error --retry 5 \
     https://bootstrap.pypa.io/get-pip.py | sudo python2.7