Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 104 additions & 22 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -26,18 +26,19 @@ permissions:
contents: read

jobs:
build:
# Release-tag preflight, in its own job so it fails fast and in parallel with
# the checks. Releases come only from main: a v* tag on any other commit (e.g.
# an unmerged branch) would otherwise build a draft release. The checkout is
# shallow, so fetch main's full history before asking whether the tagged
# commit is reachable from it.
tag-check:
if: startsWith(github.ref, 'refs/tags/v')
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v5

# Releases come only from main: a v* tag on any other commit (e.g. an
# unmerged branch) would otherwise build a draft release. The checkout is
# shallow, so fetch main's full history before asking whether the tagged
# commit is reachable from it. Runs first, before any expensive step.
- name: Check tagged commit is on main
if: startsWith(github.ref, 'refs/tags/v')
env:
TAG: ${{ github.ref_name }}
run: |
Expand All @@ -56,10 +57,9 @@ jobs:
with:
version: 2026.9.15

# Fail before the expensive steps if a release tag disagrees with the
# Fail before the package is built if a release tag disagrees with the
# version the packages would be stamped with.
- name: Check tag matches project version
if: startsWith(github.ref, 'refs/tags/v')
env:
TAG: ${{ github.ref_name }}
run: |
Expand All @@ -69,26 +69,39 @@ jobs:
exit 1
fi

# generate -> lint -> typing -> security (bandit + pip-audit) ->
# tests with coverage (3.11–3.14) -> docs
- name: Release checks
run: hatch run release
# Everything in `hatch run release` except the tests, which run in `test`.
checks:
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v5

- name: Install toolchain (mise)
uses: jdx/mise-action@9149ea85001c7435d5a66bb127d6a1b6227cb0a5 # v5.0.0
with:
version: 2026.9.15

# `release` regenerates models.py from the pinned spec artifact. A diff
# means the committed file is not what the pin generates.
# means the committed file is not what the pin generates. The `test`
# jobs run against the committed file, so this check is what ties their
# result to the generated one.
- name: Generate models
run: hatch run generate

- name: Check that the committed models.py matches the generated one
run: git diff --exit-code -- src/oscal_bindings/v1/models.py

- name: Build wheel and sdist
run: hatch build
- name: Lint
run: hatch run lint

# always(): keep partial output for debugging when an earlier step fails.
- name: Upload coverage report
uses: actions/upload-artifact@v4
if: ${{ always() }}
with:
name: coverage-html
path: htmlcov/
- name: Typing
run: hatch run typing

- name: Security
run: hatch run security

- name: Docs
run: hatch run docs

- name: Upload API docs
uses: actions/upload-artifact@v4
Expand All @@ -97,6 +110,75 @@ jobs:
name: api-docs
path: build/api-docs/

# One job per Python in the hatch-test matrix, run in parallel. Keep the list
# in step with [[tool.hatch.envs.hatch-test.matrix]] in pyproject.toml.
# Coverage is measured on the newest Python only (`cover`); keep that entry
# in step with the Python in mise.toml.
test:
name: test (${{ matrix.python }})
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
include:
- python: "3.11"
- python: "3.12"
- python: "3.13"
- python: "3.14"
cover: true

steps:
- uses: actions/checkout@v5

- name: Install toolchain (mise)
uses: jdx/mise-action@9149ea85001c7435d5a66bb127d6a1b6227cb0a5 # v5.0.0
with:
version: 2026.9.15

- name: Test
env:
PYTHON: ${{ matrix.python }}
COVER: ${{ matrix.cover && '--cover' || '' }}
run: hatch test $COVER --python "$PYTHON"

# always(): keep partial output for debugging when a test fails.
- name: Upload coverage report
uses: actions/upload-artifact@v4
if: ${{ always() && matrix.cover }}
with:
name: coverage-html
path: htmlcov/

# The one required status check (branch protection requires `build`). A job
# whose `needs` failed is skipped, and a skipped required check counts as
# passing, so this job runs regardless and fails itself if anything upstream
# failed. It builds the packages only after every check and every Python in
# the matrix has passed, so PyPI still gets files that were tested.
build:
needs: [tag-check, checks, test]
if: ${{ !cancelled() }}
runs-on: ubuntu-latest

steps:
- name: Require upstream jobs
env:
RESULTS: ${{ join(needs.*.result, ' ') }}
run: |
echo "upstream results: $RESULTS"
case " $RESULTS " in
*" failure "*|*" cancelled "*) echo "::error::An upstream job did not succeed"; exit 1 ;;
esac

- uses: actions/checkout@v5

- name: Install toolchain (mise)
uses: jdx/mise-action@9149ea85001c7435d5a66bb127d6a1b6227cb0a5 # v5.0.0
with:
version: 2026.9.15

- name: Build wheel and sdist
run: hatch build

- name: Upload python packages
uses: actions/upload-artifact@v4
with:
Expand Down
14 changes: 8 additions & 6 deletions DEVELOPING.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,8 +162,8 @@ also needs network access to run `generate`, because the sdist does not ship the
does not need the schema, because the sdist ships `models.py`. `scripts/` is not a package: a script imports its
siblings by plain name, and tests load scripts through `tests/support/scripts.py`.

CI runs `git diff --exit-code -- src/oscal_bindings/v1/models.py` after `hatch run release` and before `hatch build`.
A difference fails the `build` job, so the committed `models.py` must be what the pin generates.
CI runs `git diff --exit-code -- src/oscal_bindings/v1/models.py` after `hatch run generate`, in the `checks` job.
A difference fails that job (and so `build`), so the committed `models.py` must be what the pin generates.

To change a type name, change the manifest in the store, release a new spec artifact, and move the pin. Never rename a
manifest type in the post-processor.
Expand Down Expand Up @@ -303,8 +303,9 @@ hatch test --all --cover # with coverage (terminal report + htmlcov/)
```

With `--cover`, the combined coverage report prints to the terminal and is also
written as HTML to `htmlcov/` (git-ignored). CI uploads it as the `coverage-html`
artifact.
written as HTML to `htmlcov/` (git-ignored). CI runs one `test` job per Python in
parallel and measures coverage on 3.14 only; that job uploads the `coverage-html`
artifact. Keep the CI matrix in `build.yml` in step with the hatch-test matrix.

## Releasing

Expand All @@ -314,8 +315,9 @@ after CI.
1. Bump `version` in `pyproject.toml` and merge it to `main`.
2. Tag that commit `v<version>` (e.g. `v0.2.0`) and push the tag.
3. CI (`build.yml`) fails fast if the tagged commit isn't on `main` or the tag isn't
`v$(hatch version)`. It then runs the full release chain, builds, and creates a
**draft** GitHub release with the wheel and sdist attached.
`v$(hatch version)` (the `tag-check` job). The `checks` job and one `test` job per
Python run in parallel; `build` then builds the packages only if all passed, and
the tag run creates a **draft** GitHub release with the wheel and sdist attached.
4. Review the draft and publish it. That triggers `release.yml`, which downloads the
attached files, checks their filenames match the tag, and uploads them to PyPI
via trusted publishing.
Expand Down
Loading