Skip to content

Contributing overview

Contributing In General¤

Our project welcomes external contributions. If you have an itch, please feel free to scratch it.

To contribute code or documentation, please submit a pull request.

A good way to familiarize yourself with the codebase and contribution process is to look for and tackle low-hanging fruit in the issue tracker. Before embarking on a more ambitious contribution, please quickly get in touch with us.

Note: We appreciate your effort, and want to avoid a situation where a contribution requires extensive rework (by you or by us), sits in backlog for a long time, or cannot be accepted at all!

Proposing new features¤

If you would like to implement a new feature, please raise an issue labelled enhancement before sending a pull request so the feature can be discussed. This is to avoid you wasting your valuable time working on a feature that the project developers are not interested in accepting into the code base.

Fixing bugs¤

If you would like to fix a bug, please raise an issue labelled bug before sending a pull request so it can be tracked.

Merge approval¤

The project maintainers use LGTM (Looks Good To Me) in comments on the code review to indicate acceptance. A change requires LGTMs from one of the maintainers.

For a list of the maintainers, see the maintainers page.

Trestle updating, testing and release logistics¤

Contributors should make a working copy (branch or fork) from the develop branch of trestle. Contributors should update the working copy with changes, then create a pull request to merge into the develop branch. Contributors must include test cases to meet at least the minimum code coverage requirements. Upon approval from reviewer(s), the working copy is squashed and merged into the develop branch. Upon a cadence established by the maintainers, the develop branch is merged into the main branch and a new release is uniquely numbered and pushed to pypi.

trestle employs semantic release to automatically control release numbering. Code deliveries should be tagged with prefix fix: for changes that are bug fixes or feat: for changes that are new features. See allowed_tags for a list of supported tags.

Trestle merging and release workflow¤

trestle is operating on a simple, yet opinionated, method for continuous integration. It's designed to give developers a coherent understanding of the objectives of other past developers. The criteria for this are below. Trestle effectively uses a gitflow workflow with one modification: PR's merge into develop are squash merged as one commit.

In trestle's CI environment this results in the following rules:

  1. All Commit's MUST be signed off with git commit --signoff irrespective of the author's affiliation. This ensures all code can be attributed.
  2. This is enforced by DCO bot and can be overrided by maintainers presuming at least one commit is signed-off.
  3. All commits SHOULD use conventional commits
  4. This is as github, when only one commit is in a PR, will use the native git commit message as the merge commit title.
    1. When only a single commit is provided the commit MUST be an conventional commit and will be checked the Lint PR aciton.
  5. All PR's title's MUST be formed as an convention commit
  6. This is checked by the Lint PR action
  7. All PR's to develop and hotfix PR's to main must close at least one issue by linking the PR to an issue.
  8. Trestle will release on demand the default approach for a hot fix should be to merge into develop, followed by releasing to main, unless this will release functionality that is not ready.
  9. Each feature/fix/chore (PR into develop) be represented by a single commit into develop / main with a coherent title (in the PR).
  10. The trestle preference for doing this is to use squash merge functionality when merging a PR into develop.
  11. Developers MUST pass the required CI checks for each PR.
  12. Developers are encouraged to use GitHub's automated merge process where possible to keep the number of active PR's low.

Merge details for committers:¤

  1. All merges into develop MUST be conducted by a squash-merge
  2. All merges from develop into main MUST be done by a merge commit (e.g. preserving the history of commits into the develop branch).
  3. Hotfixes into main, not via develop, MUST be done via a squash merge.
  4. Merge's into any branch excluding main and develop are at the developers choice.
  5. Use of autocommit is encouraged to ensure commit messages and squash vs merge commit are completed properly.

Working from a fork¤

  1. In order not to break Github Actions security model SonarCloud will not run on a fork.
  2. Given this a maintainer MAY determine that sonar needs to be run and ask you to first merge your branch to a staging branch, after reviewing for security risks in the CI pipeline.
  3. From this staging branch sonar would be run and then the code merged.

Typing, docstrings and documentation¤

trestle has a goal of using PEP 484 type annotations where possible / practical. The devops process does not strictly enforce typing, however, the expectation is that type coverage is added for new commits with a focus on quality over quantity (e.g. don't add Any everywhere just to meet coverage requirements). Python typing of functions is an active work in progress.

mkbuild is used to generate the trestle documenation site. The mkbuild website includes an API reference section generated from the code. Docstrings within the code are expected to follow google style docstrings.

Each source file must include a license header for the Apache Software License 2.0. Using the SPDX format is the simplest approach. e.g.

# Copyright (c) 2024 The OSCAL Compass Authors. All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

We have tried to make it as easy as possible to make contributions. This applies to how we handle the legal aspects of contribution. We use the same approach - the Developer's Certificate of Origin 1.1 (DCO) - that the Linux® Kernel community uses to manage code contributions.

We simply ask that when submitting a patch for review, the developer must include a sign-off statement in the commit message.

Here is an example Signed-off-by line, which indicates that the submitter accepts the DCO:

Signed-off-by: John Doe <john.doe@example.com>

You can include this automatically when you commit a change to your local git repository using the following command:

git commit --signoff

Note that DCO signoff is enforced by DCO bot. Missing DCO's will be required to be rebased with a signed off commit before being accepted.

Setup - Developing trestle¤

Does trestle run correctly on my platform¤

  • (Optional) setup a venv for python
  • Run make develop
  • This will install all python dependencies
  • It will also checkout the submodules required for testing.
  • Run make test
  • This should run on all platforms

Setting up vscode for python.¤

  • Use the following commands to setup python:
python3 -m venv venv
. ./venv/bin/activate
# for zsh put .[dev] in quotes as below
pip install -q -e ".[dev]" --upgrade --upgrade-strategy eager

  • Install vscode plugin Python extension for Visual Studio Code

  • Enable yapf for code formatting

  • Enable flake8 for code linting

Testing python in vscode¤

Tests should be in the test subdirectory. Each file should be named test_*.py and each test function should be named *_test().

Note that with Python3 there should be no need for init.py in directories.

Test discovery should be automatic when you select a .py file for editing. After tests are discovered a flask icon will appear on the left and you can select it to see a panel listing of your tests. In addition your test functions will be annotated with Run/Debug so they can be launched directly from the editor. When everything is set up properly you should be able to step through your test code - which is important.

Sometimes the discovery fails - and you may need to resort to uninstalling the python extension and reinstalling it - perhaps also shutting down code and restarting. This is a lightweight operation and seems to be safe and usually fixes any problems.

Test discovery will fail or stop if any of the tests have errors in them - so be sure to monitor the Problems panel at the bottom for problems in the code.

Note that there are many panels available in Output - so be sure to check Python Test Log for errors and output from the tests.

pytest fixtures are available to allow provision of common functionality. See conftest.py and tmp_dir for an example.

NIST reference data for testing.¤

Trestle relies on reference data from two NIST repositories for testing:

Both of these repositories are submodules in the trestle project. In order to develop / test trestle the submodules must be checked out with git submodule update --init or make submodules.

Code testing¤

Tests must exist for at least 96% of trestle Python code. To determine the code coverage locally during development:

make test-cov

A PR without sufficient test coverage will fail the trestle CI process and will not be approved or merged.

Additional code scrutiny is applied in the trestle CI pipeline by SonarCloud. Any failures must be addressed before code merging.

Code style and formating¤

Python code should generally follow PEP 8.

trestle uses yapf for code formatting and flake8 for code styling. It also uses pre-commit hooks that are integrated into the development process and the CI. When you run make develop you are ensuring that the pre-commit hooks are installed and updated to their latest versions for this repository. This ensures that all delivered code has been properly formatted and passes the linter rules. See the pre-commit configuration file for details on yapf and flake8 configurations.

Since yapf and flake8 are installed as part of the pre-commit hooks, running yapf and flake8 manually must be done through pre-commit. See examples below:

make code-format
make code-lint

...will run yapf and flake8 on the entire repo and is equivalent to:

pre-commit run yapf --all-files
pre-commit run flake8 --all-files

...and when looking to limit execution to a subset of files do similar to:

pre-commit run yapf --files trestle/*
pre-commit run flake8 --files trestle/*

Note that in both of these cases autogenerated files under trestle/oscal are excluded. Note that for IDE support setup.cfg maintains a cache of flake8 configuration.

Developers Guide to trestle upgrade commensurate with OSCAL models upgrade¤

This is a general guide on how to go about upgrading compliance-trestle to support a new version of OSCAL models.

The steps are as follows:

  1. Create in GitHub repo (remote)
  2. Clone upgrade branch into /trestle-upgrade folder (local <- remote)
  3. Download revised and new OSCAL models into folder /trestle-upgrade/release-schemas (local <- remote)
  4. Create & source python virtual environment venv.trestle-upgrade (local)
  5. Orient current folder to /trestle-upgrade (local)
  6. Run make develop (local)
  7. Make necessary code changes:
    • Run python scripts/gen_oscal.py (local)
    • Run make test-all (local)
    • Fix errors and failures via modification of code generation modules and existing trestle modules, as appropriate case-by-case (local)
    • Repeat until all errors and failures are fixed (local)
  8. Run make code-format (local)
  9. Run make code-lint (local)
  10. Push /trestle-upgrade folder changes back to GitHub repo (local -> remote)
  11. Create PR for trestle-upgrade branch -> develop branch (remote)
  12. Get PR approval (remote)
  13. Merge PR into develop branch (remote)
  14. Create PR for develop branch -> main branch (remote)
  15. Create breaking change (remote)
  16. Get PR approval (remote)
  17. Merge develop branch into main branch (remote)
Overview of process to take OSCAL models and upgrade trestle Python code¤