Merge pull request #1774 from oscal-compass/develop

chore: trestle release

.github/CODEOWNERS

@@ -0,0 +1,3 @@
+# These owners will be the default owners for everything in
+# the repo.
+*       @oscal-compass/compliance-trestle-maintainers

.github/workflows/docs-update.yml

@@ -0,0 +1,91 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+name: Trestle Docs update
+on:
+  push:
+    branches:
+    - develop
+    tags:
+    - v*
+
+jobs:
+  set-versions:
+    runs-on: ubuntu-latest
+    outputs:
+      min: ${{ steps.versions.outputs.min }}
+      max: ${{ steps.versions.outputs.max }}
+    steps:
+    - uses: actions/checkout@v4
+    - id: versions
+      run: |
+        min_version=$(jq '.PYTHON_MIN' -r version.json)
+        max_version=$(jq '.PYTHON_MAX' -r version.json)
+        echo "min=$min_version" 
+        echo "max=$max_version"
+        echo "min=$min_version" >> $GITHUB_OUTPUT
+        echo "max=$max_version" >> $GITHUB_OUTPUT
+  mike-version:
+    runs-on: ubuntu-latest
+    needs: [ set-versions ]
+    outputs:
+      mver: ${{ steps.versions.outputs.mver }}
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ needs.set-versions.outputs.max }}
+      uses: actions/setup-python@v5
+      # This is deliberately not using a custom credential as it relies on native github actions token to have push rights.
+      with:
+        python-version: ${{ needs.set-versions.outputs.max }}
+    - id: versions
+      env:
+        REF: ${{ github.event.ref }}
+      run: |
+        mike_version=$(python ./scripts/mike_version_parse.py "$REF")
+        echo "mver=$mike_version" >> $GITHUB_OUTPUT
+  deploy-docs:
+    runs-on: ubuntu-latest
+    needs: [ mike-version, set-versions ]
+    steps:
+    - uses: actions/create-github-app-token@v1
+      id: app-token
+      with:
+        app-id: ${{ secrets.APP_ID }}
+        private-key: ${{ secrets.PRIVATE_KEY }}
+    - uses: actions/checkout@v4
+      with:
+        submodules: true
+        fetch-depth: 0
+        token: ${{ steps.app-token.outputs.token }}
+    - name: Set up Python ${{ needs.set-versions.outputs.max }}
+      uses: actions/setup-python@v5
+      # This is deliberately not using a custom credential as it relies on native github actions token to have push rights.
+      with:
+        python-version: ${{ needs.set-versions.outputs.max }}
+    - name: Install build tools
+      run: |
+        make develop
+    - name: Install documenation dependencies
+      run: |
+        make docs-ubuntu-deps
+    
+    - name: Get GitHub App User ID
+      id: get-user-id
+      run: echo "user-id=$(gh api "/users/${{ env.SLUG }}[bot]" --jq .id)" >> "$GITHUB_OUTPUT"
+      env:
+        GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        SLUG: ${{ steps.app-token.outputs.app-slug }}
+    - name: Configure Git
+      run: |
+        git config --global user.name '${{ env.SLUG }}[bot]'
+        git config --global user.email '${{ env.ID }}+${{ env.SLUG }}[bot]@users.noreply.github.com'
+      env:
+        SLUG: ${{ steps.app-token.outputs.app-slug }}
+        ID: ${{ steps.get-user-id.outputs.user-id }}
+    - name: Create release
+      shell: bash
+      run: |
+        mike deploy --push ${{ needs.mike-version.outputs.mver }}
+    - name: Ensure latest is latest
+      shell: bash
+      run: | 
+        mike set-default latest

.github/workflows/python-push.yml

@@ -90,6 +90,10 @@ jobs:
       continue-on-error: true 
       run: |
         make code-typing
+    - name: Install documenation dependencies
+      if: steps.core-version.outputs.core == 'true'
+      run: |
+        make docs-ubuntu-deps
     - name: Validate website content (mkdocs)
       if: steps.core-version.outputs.core == 'true'
       run: |
@@ -149,38 +153,6 @@ jobs:
       with:
         github_token: ${{ steps.app-token.outputs.token }}
 
-  deploy-docs:
-    runs-on: ubuntu-latest
-    needs: [ deploy, set-versions ]
-    concurrency: 
-      group: ${{ github.ref }}-${{ github.workflow }}-${{ github.job }}-docs
-      cancel-in-progress: true
-    # Temporary hack: allow develop as well as master to deploy docs.
-    if: github.ref == 'refs/heads/main'
-    steps:
-    - uses: actions/create-github-app-token@v1
-      id: app-token
-      with:
-        app-id: ${{ secrets.APP_ID }}
-        private-key: ${{ secrets.PRIVATE_KEY }}
-    - uses: actions/checkout@v4
-      with:
-        submodules: true
-        fetch-depth: 0
-        token: ${{ steps.app-token.outputs.token }}
-    - name: Set up Python ${{ needs.set-versions.outputs.max }}
-      uses: actions/setup-python@v5
-      # This is deliberately not using a custom credential as it relies on native github actions token to have push rights.
-      with:
-        python-version: ${{ needs.set-versions.outputs.max }}
-    - name: Install build tools
-      run: |
-        make develop
-    - name: Create release
-      shell: bash
-      run: |
-        mkdocs gh-deploy
-
   merge-main-to-develop:
     name: Merge main -> develop
     runs-on: ubuntu-latest

.github/workflows/python-test.yml

@@ -62,6 +62,9 @@ jobs:
       continue-on-error: true
       run: |
         make code-typing
+    - name: Install documenation dependencies
+      run: |
+        make docs-ubuntu-deps
     - name: Validate website content (mkdocs)
       run: |
         make docs-validate

.gitignore

@@ -51,3 +51,5 @@ tmp_bin_test
 
 /venv.trestle/
 
+# mkdocs
+.cache/

.pre-commit-config.yaml

@@ -73,7 +73,7 @@ repos:
     rev: 0.7.17
     hooks:
     - id: mdformat
-      exclude: "CHANGELOG.md|docs/mkdocs_code_of_conduct.md|docs/maintainers.md|docs/api_reference|tests/data/author|docs/contributing/mkdocs_contributing.md|tests/data/jinja_markdown_include|tests/data/jinja_cmd/number_captions_data.md|tests/data/jinja_cmd/number_captions_expected_output.md"
+      exclude: "CHANGELOG.md|docs/contributing/maintainers.md|docs/reference/API|tests/data/author|docs/contributing/index.md|tests/data/jinja_markdown_include|tests/data/jinja_cmd/number_captions_data.md|tests/data/jinja_cmd/number_captions_expected_output.md"
       additional_dependencies:
       - mdformat-tables
       - mdformat-config

CONTRIBUTING.md

@@ -28,9 +28,11 @@ 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.
+review to indicate acceptance.
 
-For a list of the maintainers, see the [maintainers](https://oscal-compass.github.io/compliance-trestle/maintainers/) page.
+A change requires LGTMs from at least two reviewers. One of the reviewers must be a [`CODEOWNER`](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners).
+
+For a list of the maintainers (also codeowners), see the [maintainers](https://oscal-compass.github.io/compliance-trestle/maintainers/) page.
 
 ### Trestle updating, testing and release logistics
 
@@ -41,7 +43,7 @@ Upon approval from reviewer(s), the working copy is squashed and merged into the
 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](https://pypi.org/project/compliance-trestle/).
 
 `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](https://python-semantic-release.readthedocs.io/en/latest/commit-parsing.html#:~:text=The%20default%20configuration%20options%20for%20semantic_release.commit_parser.AngularCommitParser%20are%3A) for a list of supported tags.
+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](https://python-semantic-release.readthedocs.io/en/latest/commit_parsing.html#commit-parser-builtin-angular) for a list of supported tags.
 
 ### Trestle merging and release workflow
 
@@ -61,7 +63,7 @@ In trestle's CI environment this results in the following rules:
 1. 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.
 1. Each feature/fix/chore (PR into develop) be represented by a single commit into develop / main with a coherent title (in the PR).
    1. The trestle preference for doing this is to use squash merge functionality when merging a PR into develop.
-1. Developers *MUST* pass the required CI checks for each PR.
+1. Developers *MUST* pass the required CI checks for each PR. The checks enforce code quality with a format checker (yapf) and linter (flake8).
 1. 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:
@@ -114,7 +116,7 @@ e.g.
 
 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://oscal-compass.github.io/compliance-trestle/contributing/DCO/) - that the Linux® Kernel [community](https://elinux.org/Developer_Certificate_Of_Origin)
+same approach - the [Developer's Certificate of Origin 1.1 (DCO)](https://oscal-compass.github.io/compliance-trestle/contributing/DCO/) - that the Linux® Kernel [community](https://developercertificate.org/)
 uses to manage code contributions.
 
 We simply ask that when submitting a patch for review, the developer

Makefile

@@ -82,11 +82,17 @@ release::
 gen-oscal::
 	python ./scripts/gen_oscal.py
 
+docs-osx-deps:
+	brew install cairo freetype libffi libjpeg libpng zlib
+
+docs-ubuntu-deps:
+	sudo apt-get -y install libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
+
 docs-automation::
 	python ./scripts/website_automation.py
 
 docs-validate:: docs-automation
-	mkdocs build -v -c -s
+	mkdocs build -c -s
 	rm -rf site
 
 docs-serve: docs-automation

README.md

@@ -7,6 +7,7 @@
 ![[Quality gate](https://sonarcloud.io/dashboard?id=compliance-trestle)](https://sonarcloud.io/api/project_badges/measure?project=compliance-trestle&metric=alert_status)
 ![[Pypi](https://pypi.org/project/compliance-trestle/)](https://img.shields.io/pypi/dm/compliance-trestle)
 ![GitHub Actions status](https://github.com/oscal-compass/compliance-trestle/actions/workflows/python-test.yml/badge.svg?branch=develop)
+![OpenSSF Best Practices](https://www.bestpractices.dev/projects/9408/badge)
 
 Trestle is an ensemble of tools that enable the creation, validation, and governance of documentation artifacts for compliance needs. It leverages NIST's [OSCAL](https://pages.nist.gov/OSCAL/) as a standard data format for interchange between tools and people, and provides an opinionated approach to OSCAL adoption.