Contributing

Local Workflow

StatePlane uses uv for environment and command management.

Install everything:

uv sync --all-packages --all-groups --python 3.13

Recommended verification before opening a PR:

uv run --all-packages --all-groups --python 3.13 ruff format --check .
uv run --all-packages --all-groups --python 3.13 ruff check .
uv run --all-packages --all-groups --python 3.13 mypy packages services tests examples
uv run --all-packages --all-groups --python 3.13 pyright
uv run --all-packages --all-groups --python 3.13 mkdocs build --strict
uv run --all-packages --all-groups --python 3.13 pytest tests/unit tests/integration --cov=packages --cov=services --cov-report=term-missing --cov-fail-under=95

Documentation Maintenance

Serve the docs locally:

uv run --all-packages --all-groups --python 3.13 mkdocs serve

Build them exactly as CI does:

uv run --all-packages --all-groups --python 3.13 mkdocs build --strict

The generated site is written to site/ during mkdocs build.

GitHub Pages

The repository includes a GitHub Pages workflow in .github/workflows/docs.yml.

To finish or verify setup in GitHub:

1. Open the repository settings.
2. Go to Pages.
3. Set the source to GitHub Actions.

After that, pushes to main build and deploy the docs site automatically.

Documentation Expectations

• keep README files, docs pages, examples, and tests aligned with repo reality
• update mkdocs.yml navigation when adding, removing, or renaming docs pages
• keep the docs build passing under mkdocs build --strict
• prefer current-state docs over aspirational marketing copy

Testing Expectations

• add or update tests with each behavior change
• keep unit tests focused on deterministic behavior and invariants
• use integration tests for package, CLI, and boundary-level flows
• do not lower type, lint, or coverage gates to force green CI

Pull Requests

• open PRs as ready for review by default
• keep changes scoped and intentional
• include the checks you ran in the PR description