From d56468f98ab1353ca3d97d26976c2008cccdbfe7 Mon Sep 17 00:00:00 2001 From: Major Hayden Date: Wed, 8 Jun 2016 13:07:06 -0500 Subject: [PATCH] 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 | 67 ++++++++++++++++++++++++++++++++++ doc/source/index.rst | 2 +- doc/source/writing-docs.rst | 12 ------ run_tests.sh | 11 ++++-- 4 files changed, 76 insertions(+), 16 deletions(-) create mode 100644 doc/source/developer-guide.rst delete mode 100644 doc/source/writing-docs.rst diff --git a/doc/source/developer-guide.rst b/doc/source/developer-guide.rst new file mode 100644 index 00000000..a3709273 --- /dev/null +++ b/doc/source/developer-guide.rst @@ -0,0 +1,67 @@ +.. include:: +`Home `__ |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 `_ diff --git a/doc/source/index.rst b/doc/source/index.rst index 8c47dd0c..9fc1b2e8 100644 --- a/doc/source/index.rst +++ b/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 =================================================== diff --git a/doc/source/writing-docs.rst b/doc/source/writing-docs.rst deleted file mode 100644 index 91c2ad96..00000000 --- a/doc/source/writing-docs.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. include:: -`Home `__ |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``. diff --git a/run_tests.sh b/run_tests.sh index 9d5ed19a..69275f04 100755 --- a/run_tests.sh +++ b/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