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/rhel7. Here is an example of RHEL-07-020210:

---
id: RHEL-07-020210
status: implemented
tag: lsm
---

The tasks in the security role enable the appropriate Linux Security Module
(LSM) for the operating system.

For Ubuntu systems, AppArmor is installed and enabled. This change takes
effect immediately.

For CentOS or Red Hat Enterprise Linux systems, SELinux is enabled (in
enforcing mode) and its user tools are automatically installed. If SELinux is
not in enforcing mode already, a reboot is required to enable SELinux and
relabel the filesystem.

.. warning::

    Relabeling a filesystem takes time and the server must be offline for the
    relabeling to complete. Filesystems with large amounts of files and
    filesystems on slow disks will cause the relabeling process to take more
    time.

Deployers can opt out of this change by setting the following Ansible variable:

.. code-block:: yaml

    security_rhel7_enable_linux_security_module: no

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