docs: update development guide and add usage documentation (#15) #28
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # --- | |
| # Workflow: CI | |
| # | |
| # Runs on every push and pull request targeting main or devel. | |
| # Validates formatting, linting, type safety, and security before running | |
| # the full test matrix. A passing run is required before merging. | |
| # | |
| # Job graph: | |
| # lint ─┐ | |
| # typecheck ─┼─► test (py3.10–3.13 via tox) | |
| # security ──┘─► coverage (py3.11, uploads XML artifact) | |
| # | |
| # Secrets required: none | |
| # Produces: coverage-xml artifact (7-day retention) | |
| # --- | |
| --- | |
| name: CI | |
| on: | |
| push: | |
| branches: [main, devel] | |
| pull_request: | |
| branches: [main, devel] | |
| # Cancel in-progress runs for the same branch on new push. | |
| # Keeps PR queues clean without burning extra minutes. | |
| concurrency: | |
| group: ${{ github.workflow }}-${{ github.ref }} | |
| cancel-in-progress: true | |
| # Least-privilege default — no job needs write access. | |
| permissions: | |
| contents: read | |
| jobs: | |
| # -- lint | |
| # Checks formatting (ruff format) and style (ruff check). | |
| # Runs unconditionally; all other jobs gate on this passing. | |
| lint: | |
| name: Lint | |
| runs-on: ubuntu-24.04 | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - uses: actions/setup-python@v5 | |
| with: | |
| python-version: "3.11" | |
| # setup-uv handles uv install and caches ~/.cache/uv keyed on uv.lock | |
| - uses: astral-sh/setup-uv@v5 | |
| # Security: pin to a full commit SHA once the release SHA is confirmed. | |
| # https://github.com/astral-sh/setup-uv/releases/tag/v5 | |
| with: | |
| enable-cache: true | |
| - name: Install dependencies | |
| run: make install | |
| - name: Check formatting | |
| run: make format-check | |
| - name: Run linter | |
| run: make lint | |
| # -- typecheck | |
| # Static type analysis with mypy. Runs in parallel with lint and security. | |
| typecheck: | |
| name: Type Check | |
| runs-on: ubuntu-24.04 | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - uses: actions/setup-python@v5 | |
| with: | |
| python-version: "3.11" | |
| - uses: astral-sh/setup-uv@v5 | |
| with: | |
| enable-cache: true | |
| - name: Install dependencies | |
| run: make install | |
| - name: Run mypy | |
| run: make typecheck | |
| # -- security | |
| # Bandit SAST scan. Runs in parallel with lint and typecheck. | |
| security: | |
| name: Security | |
| runs-on: ubuntu-24.04 | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - uses: actions/setup-python@v5 | |
| with: | |
| python-version: "3.11" | |
| - uses: astral-sh/setup-uv@v5 | |
| with: | |
| enable-cache: true | |
| - name: Install dependencies | |
| run: make install | |
| - name: Run bandit | |
| run: make security | |
| # -- test | |
| # Full test suite across all supported Python versions via tox. | |
| # Runs only after all three quality gates pass. | |
| # fail-fast: false ensures we see results for every version on failure. | |
| test: | |
| name: Test (Python ${{ matrix.python-version }}) | |
| needs: [lint, typecheck, security] | |
| runs-on: ubuntu-24.04 | |
| strategy: | |
| fail-fast: false | |
| matrix: | |
| include: | |
| - python-version: "3.10" | |
| tox-env: py310 | |
| - python-version: "3.11" | |
| tox-env: py311 | |
| - python-version: "3.12" | |
| tox-env: py312 | |
| - python-version: "3.13" | |
| tox-env: py313 | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - uses: actions/setup-python@v5 | |
| with: | |
| python-version: ${{ matrix.python-version }} | |
| - uses: astral-sh/setup-uv@v5 | |
| with: | |
| enable-cache: true | |
| - name: Install dependencies | |
| run: make install | |
| - name: Run tests via tox | |
| run: make tox-${{ matrix.tox-env }} | |
| # -- coverage | |
| # Generates an XML coverage report on py3.11 and posts a summary to the | |
| # Actions job summary page. Artifact is retained for 7 days. | |
| # Runs after quality gates pass, in parallel with the test matrix. | |
| coverage: | |
| name: Coverage | |
| needs: [lint, typecheck, security] | |
| runs-on: ubuntu-24.04 | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - uses: actions/setup-python@v5 | |
| with: | |
| python-version: "3.11" | |
| - uses: astral-sh/setup-uv@v5 | |
| with: | |
| enable-cache: true | |
| - name: Install dependencies | |
| run: make install | |
| - name: Run tests with coverage | |
| run: make coverage | |
| - name: Write coverage summary | |
| run: | | |
| echo "## Coverage Report" >> $GITHUB_STEP_SUMMARY | |
| echo '```' >> $GITHUB_STEP_SUMMARY | |
| uv run coverage report >> $GITHUB_STEP_SUMMARY | |
| echo '```' >> $GITHUB_STEP_SUMMARY | |
| - name: Upload coverage artifact | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: coverage-xml | |
| path: coverage.xml | |
| retention-days: 7 |