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:

./run_tests.sh

Writing documentation¶

Documentation consists of two parts: metadata and deployer notes. The metadata exists as YAML frontmatter for each STIG configuration. The frontmatter is followed by the text of the deployer note itself.

All of the notes are found within doc/metadata/rhel6. Here is an example of V-38497:

---
id: V-38497
status: implemented
tag: auth
---

Ubuntu 14.04, Ubuntu 16.04, and CentOS 7 allow accounts with null passwords to
authenticate via PAM by default. This STIG requires that those login attempts
are blocked.

For Ubuntu, the ``nullok_secure`` option will be removed from ``/etc/pam.d
/common-auth``.

For CentOS, the ``nullok`` option will be removed from ``/etc/pam.d/system-
auth``.

The effects of the change are **immediate** and no service restarts are
required.

Deployers can opt-out of this change by adjusting an Ansible variable:

.. code-block:: yaml

    security_pam_remove_nullok: no

Setting the variable to ``yes`` (the default) will cause the Ansible tasks to
remove the ``nullok_secure`` parameter while setting the variable to ``no``
will leave the PAM configuration unchanged.

The block after the first three dashes (---) is the metadata. The metadata must include:

• id: The ID of the STIG configuration item.
• status: The implementation status of the STIG configuration, such as implemented, exception, or opt-in.
• tag: The Ansible tag associated with the task(s) that make changes based on the STIG requirement, such as auditd, kernel, or lsm.

The next block is the deployer note. The note 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?

Run tox -e docs to rebuild the documentation from the metadata and review your changes.

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:

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