diff --git a/.github/ISSUE_TEMPLATE/new_collaborator.md b/.github/ISSUE_TEMPLATE/new_collaborator.md index 2157f61..2660b26 100644 --- a/.github/ISSUE_TEMPLATE/new_collaborator.md +++ b/.github/ISSUE_TEMPLATE/new_collaborator.md @@ -14,4 +14,4 @@ I would like collaborator (write) access to this repository. - help make & test releases - help promote the project -[contributing]: https://github.com/IBM/compliance-trestle/blob/main/CONTRIBUTING.md +[contributing]: https://github.com/oscal-compass/compliance-trestle-fedramp/blob/main/CONTRIBUTING.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 3104152..8d96eb3 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -16,4 +16,4 @@ ## Key links: -- [Sonar coverage](https://sonarcloud.io/dashboard?id=compliance-trestle) +- [Sonar coverage](https://sonarcloud.io/dashboard?id=compliance-trestle-fedramp) diff --git a/.github/workflows/python-push.yml b/.github/workflows/python-push.yml index 2e09088..a691788 100644 --- a/.github/workflows/python-push.yml +++ b/.github/workflows/python-push.yml @@ -8,53 +8,7 @@ on: - main jobs: - lint: - runs-on: ubuntu-latest - steps: - - name: Don't mess with line endings - run: | - git config --global core.autocrlf false - - name: Don't mess with line endings - run: | - git config --global core.autocrlf false - - uses: actions/checkout@v2 - with: - submodules: true - - name: Set up Python - uses: actions/setup-python@v2 - with: - python-version: 3.9 - - uses: actions/cache@v2 - with: - path: ~/.cache/pip - key: ubuntu-latest-3.9-pip-${{ hashFiles('setup.cfg') }} - restore-keys: | - ubuntu-latest-3.9-pip- - - name: Install build tools - run: | - make develop - - name: Setup pre-commit - run: | - make pre-commit - - name: Install dependencies - run: | - make install - - name: Run md document formatting (mdformat) - run: | - make mdformat - - name: Run code formatting (yapf) - run: | - make code-format - - name: Run code linting (flake8) - run: | - make code-lint - - name: Run code typing check (mypy) - continue-on-error: true - run: | - make code-typing - - test: - # This test + build: runs-on: ${{ matrix.os }} strategy: matrix: @@ -74,7 +28,6 @@ jobs: git config --global core.autocrlf false - uses: actions/checkout@v2 with: - fetch-depth: 0 submodules: true - name: Set up Python ${{ matrix.python-version }} uses: actions/setup-python@v2 @@ -87,14 +40,33 @@ jobs: restore-keys: | ${{ matrix.os }}-${{ matrix.python-version }}-pip- - # Windows Dev tools - - name: Install microsoft dev tools - if: ${{ matrix.os == 'windows-latest' }} - uses: ilammy/msvc-dev-cmd@v1 - - name: Install build tools run: | make develop + - name: Setup pre-commit + if: ${{ (matrix.os == 'ubuntu-latest' && matrix.python-version == '3.8') }} + run: | + make pre-commit + - name: Install dependencies + run: | + make install + - name: Run md document formatting (mdformat) + if: ${{ (matrix.os == 'ubuntu-latest' && matrix.python-version == '3.8') }} + run: | + make mdformat + - name: Run code formatting (yapf) + if: ${{ (matrix.os == 'ubuntu-latest' && matrix.python-version == '3.8') }} + run: | + make code-format + - name: Run code linting (flake8) + if: ${{ (matrix.os == 'ubuntu-latest' && matrix.python-version == '3.8') }} + run: | + make code-lint + - name: Run code typing check (mypy) + if: ${{ (matrix.os == 'ubuntu-latest' && matrix.python-version == '3.8') }} + continue-on-error: true + run: | + make code-typing - name: Pytest Fast if: ${{ !(matrix.os == 'ubuntu-latest' && matrix.python-version == '3.8') }} run: | @@ -104,69 +76,10 @@ jobs: run: | make test-cov - - name: Upload artifact - if: ${{ matrix.os == 'ubuntu-latest' && matrix.python-version == '3.8' }} - uses: actions/upload-artifact@v2 - with: - name: coverage - path: coverage.xml - - sonar: - if: github.repository == 'IBM/compliance-trestle-fedramp' - runs-on: ubuntu-latest - needs: test - steps: - - name: Don't mess with line endings - run: | - git config --global core.autocrlf false - - name: Don't mess with line endings - run: | - git config --global core.autocrlf false - - uses: actions/checkout@v2 - with: - submodules: true - - name: Set up Python - uses: actions/setup-python@v2 - with: - python-version: 3.8 - - uses: actions/cache@v2 - with: - path: ~/.cache/pip - key: ubuntu-latest-3.9-pip-${{ hashFiles('setup.cfg') }} - restore-keys: | - ubuntu-latest-3.9-pip- - - name: Install build tools - run: | - make develop - - name: Get coverage - uses: actions/download-artifact@v2 - with: - name: coverage - - name: SonarCloud Scan - uses: SonarSource/sonarcloud-github-action@master - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Needed to get PR information, if any - SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} - with: - args: > - -Dsonar.python.coverage.reportPaths=coverage.xml - -Dsonar.tests=tests/ - -Dsonar.sources=trestle_fedramp/ - -Dsonar.python.version=3.8 - -Dsonar.projectKey=compliance-trestle-fedramp - -Dsonar.organization=compliance-trestle - - name: SonarQube Quality Gate check - uses: sonarsource/sonarqube-quality-gate-action@master - # Force to fail step after specific time - timeout-minutes: 5 - env: - SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} - deploy: - runs-on: ubuntu-latest - needs: sonar - if: github.ref == 'refs/heads/main' && github.repository == 'IBM/compliance-trestle-fedramp' + needs: build + if: github.ref == 'refs/heads/main' && github.repository == 'oscal-compass/compliance-trestle-fedramp' steps: - uses: actions/checkout@v2 with: @@ -192,15 +105,24 @@ jobs: name: Merge main -> develop runs-on: ubuntu-latest needs: deploy - concurrency: + concurrency: group: ${{ github.ref }}-${{ github.workflow }}-${{ github.job }}-main cancel-in-progress: true if: github.ref == 'refs/heads/main' steps: - - uses: tukasz/direct-merge-action@master + - uses: actions/checkout@v2 with: - GITHUB_TOKEN: ${{ secrets.ADMIN_PAT }} - source-branch: main - target-branch: develop - commit-message: "chore: Merge back version tags and changelog into develop." + submodules: true + ref: main + fetch-depth: 0 + token: ${{ secrets.ADMIN_PAT }} + - name: Configure Git + run: | + git config user.name "Vikas Agarwal" + git config user.email "<>" + - name: Merge Main to Develop + run: | + git checkout develop + git merge --no-ff main -m "chore: Merge back version tags and changelog into develop." + git push origin develop diff --git a/.github/workflows/python-test.yml b/.github/workflows/python-test.yml index 3f2a879..50b0eea 100644 --- a/.github/workflows/python-test.yml +++ b/.github/workflows/python-test.yml @@ -140,7 +140,7 @@ jobs: path: coverage.xml sonar: - if: github.repository == 'IBM/compliance-trestle-fedramp' + if: github.repository == 'oscal-compass/compliance-trestle-fedramp' runs-on: ubuntu-latest needs: test steps: diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 0cbf7df..57a20dd 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -55,7 +55,7 @@ further defined and clarified by project maintainers. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at chris.butler@au1.ibm.com. All +reported by contacting the project team at avikas@in.ibm.com. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e0900a4..0b76f92 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,87 +3,131 @@ Our project welcomes external contributions. If you have an itch, please feel free to scratch it. -To contribute code or documentation, please submit a **FIXME** [pull request](https://github.com/ibm/repo-template/pulls). +To contribute code or documentation, please submit a [pull request](https://github.com/oscal-compass/compliance-trestle-fedramp/pulls). A good way to familiarize yourself with the codebase and contribution process is -to look for and tackle low-hanging fruit in the **FIXME** [issue tracker](https://github.com/ibm/repo-template/issues). -Before embarking on a more ambitious contribution, please quickly [get in touch](#communication) with us. +to look for and tackle low-hanging fruit in the [issue tracker](https://github.com/oscal-compass/compliance-trestle-fedramp/issues). +Before embarking on a more ambitious contribution, please quickly [get in touch](https://github.com/oscal-compass/compliance-trestle-fedramp/blob/develop/MAINTAINERS.md) 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!** +We have also adopted [Contributor Covenant Code of Conduct](https://oscal-compass.github.io/compliance-trestle/mkdocs_code_of_conduct/). + ### Proposing new features -If you would like to implement a new feature, please **FIXME** [raise an issue](https://github.com/ibm/repo-template/issues) -before sending a pull request so the feature can be discussed. This is to avoid +If you would like to implement a new feature, please [raise an issue](https://github.com/oscal-compass/compliance-trestle-fedramp/issues) +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 **FIXME** [raise an issue](https://github.com/ibm/repo-template/issues) before sending a +If you would like to fix a bug, please [raise an issue](https://github.com/oscal-compass/compliance-trestle-fedramp/issues) 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 two of the -maintainers of each component affected. +review to indicate acceptance. A change requires LGTMs from one of the maintainers. + +For a list of the maintainers, see the [maintainers](https://github.com/oscal-compass/compliance-trestle-fedramp/blob/develop/MAINTAINERS.md) page. + +### Merging and release workflow + +The `compliance-trestle-fedramp` project follows the same release and merging workflow `trestle` follows. Please refer to the [trestle release and merging workflow](https://github.com/oscal-compass/compliance-trestle/blob/develop/CONTRIBUTING.md#trestle-merging-and-release-workflow). -For a list of the maintainers, see the [MAINTAINERS.md](MAINTAINERS.md) page. +## Typing, docstrings and documentation + +The `compliance-trestle-fedramp` project uses type hints and docstrings to improve code readability and maintainability. Please refer to the [trestle typing, docstrings and documentation](https://github.com/oscal-compass/compliance-trestle/blob/develop/CONTRIBUTING.md#typing-docstrings-and-documentation) for more details. ## Legal -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. +By contributing to this project, you agree to license your contribution under the \[Apache 2.0 License\]. For more detailed requirements, please refer to the `trestle` Legal section in the [CONTRIBUTING.md](https://github.com/oscal-compass/compliance-trestle/blob/develop/CONTRIBUTING.md#legal). -``` -/* -Copyright All Rights Reserved. +## Setup - Developing `compliance-trestle-fedramp` -SPDX-License-Identifier: Apache-2.0 -*/ -``` +### Does `compliance-trestle-fedramp` run correctly on my platform -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)](https://github.com/hyperledger/fabric/blob/master/docs/source/DCO1.1.txt) - that the Linux® Kernel [community](https://elinux.org/Developer_Certificate_Of_Origin) -uses to manage code contributions. +- (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, except Windows (currently). -We simply ask that when submitting a patch for review, the developer -must include a sign-off statement in the commit message. +### Setting up `vscode` for python. -Here is an example Signed-off-by line, which indicates that the -submitter accepts the DCO: +- Use the following commands to setup python: -``` -Signed-off-by: John Doe +```bash +python3 -m venv venv +. ./venv/bin/activate +# for zsh put .[dev] in quotes as below +pip install -q -e ".[dev]" --upgrade --upgrade-strategy eager ``` -You can include this automatically when you commit a change to your -local git repository using the following command: +- Install vscode plugin `Python extension for Visual Studio Code` -``` -git commit -s -``` +- 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. -## Communication +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. -**FIXME** Please feel free to connect with us on our [Slack channel](link). +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. -## Setup +Note that there are many panels available in Output - so be sure to check `Python Test Log` for errors and output from the tests. -**FIXME** Please add any special setup instructions for your project to help the developer -become productive quickly. +pytest fixtures are available to allow provision of common functionality. See conftest.py and tmp_dir for an example. -## Testing +#### FedRAMP sources for development and testing -**FIXME** Please provide information that helps the developer test any changes they make -before submitting. +The `trestle` FedRAMP plugin relies on reference data from the FedRAMP automation repository for testing and development purposes. The FedRAMP automation repository is a submodule in the trestle project. The FedRAMP automation repository is located at: https://github.com/GSA/fedramp-automation -## Coding style guidelines +In order to develop/test, the submodule must be checked out with `git submodule update --init` or `make submodules`. -**FIXME** Optional, but recommended: please share any specific style guidelines you might -have for your project. +To copy required files from the submodule to the trestle-fedramp plugin, run `make fedramp-copy`. + +#### NIST OSCAL sources for development and testing + +To perform conversions from JSON to XML and vice versa, the `trestle` FedRAMP plugin relies on the NIST OSCAL schema and examples. There are available as release artifacts in the NIST OSCAL repository. The NIST OSCAL repository is located at: https://github.com/usnistgov/OSCAL + +To retrieve these artifacts, run `make download-release-artifacts`. + +### Code style and formatting + +The `trestle` FedRAMP plugin uses [yapf](https://github.com/google/yapf) for code formatting and [flake8](https://flake8.pycqa.org/en/latest/) for code styling. It also uses [pre-commit](https://pre-commit.com/) 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](https://github.com/oscal-compass/compliance-trestle-fedramp/blob/develop/.pre-commit-config.yaml) 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: + +```bash +make code-format +make code-lint +``` + +...will run `yapf` and `flake8` on the entire repo and is equivalent to: + +```bash +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: + +```bash +pre-commit run yapf --files trestle_fedramp/* +pre-commit run flake8 --files trestle_fedramp/* +``` diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 7ab24c6..7b88934 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -2,4 +2,4 @@ Vikas Agarwal - [vikas-agarwal76](https://github.com/vikas-agarwal76) -Christopher Butler - [butler54](https://github.com/butler54) +Jennifer Power [jpower432](https://github.com/jpower432) diff --git a/README.md b/README.md index 807a321..7c5f27c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # compliance-trestle-fedramp -A plugin for [compliance-trestle](https://github.com/IBM/compliance-trestle) to provide functionality specifically for FedRAMP. +A plugin for [compliance-trestle](https://github.com/oscal-compass/compliance-trestle) to provide functionality specifically for FedRAMP. This plugin provides APIs and commands for validating a FedRAMP compliant SSP (in JSON or YAML format). In future it will also provide utilities for converting various OSCAL models from XML to JSON format and vice-versa. @@ -23,7 +23,7 @@ Our project welcomes external contributions. Please consult [contributing](CONTR ## License & Authors If you would like to see the detailed LICENSE click [here](LICENSE). -Consult [contributors](https://github.com/IBM/compliance-trestle-fedramp/graphs/contributors) for a list of authors and [maintainers](MAINTAINERS.md) for the core team. +Consult [contributors](https://github.com/oscal-compass/compliance-trestle-fedramp/graphs/contributors) for a list of authors and [maintainers](MAINTAINERS.md) for the core team. ```text # Copyright (c) 2020 IBM Corp. All rights reserved. diff --git a/setup.cfg b/setup.cfg index fa5d6d6..c4f739c 100644 --- a/setup.cfg +++ b/setup.cfg @@ -5,7 +5,7 @@ description = Trestle plugin for FedRAMP validation and format conversion author = IBM author_email = avikas@in.ibm.com license = Apache Software License v2 -url = https://github.com/IBM/compliance-trestle-fedramp +url = https://github.com/oscal-compass/compliance-trestle-fedramp classifiers = Development Status :: 4 - Beta Environment :: Console