Skip to content

Contributing

Set up

make setup            # Python venv + npm install
make dev              # API on :8000, UI on :5173 (demo sign-in, SQLite, no keys)
pip install pre-commit && pre-commit install   # format and lint on every commit

Before you push

make check            # lint, format, backend + component + e2e tests with coverage floors, audits, build
make e2e              # Playwright only (starts the API and UI itself)
make fixtures         # refresh UI test fixtures after changing an API response

CI runs the same checks, plus the suite on every Python from 3.11 to 3.14, the component tests on Node 20 (the oldest supported) as well as 22, and everything against Postgres. The slow tests (make slow: full-size optimality proofs, solvers at the shipped budgets) run on pushes to main.

Conventions

  • Branches: short-lived feature branches off main; merge by pull request.
  • Commits: Conventional Commits: feat:, fix:, docs:, ci:, refactor:, test:, chore:. One logical change per commit. CI checks the subject line of every commit on pull requests and on pushes to main. Commits have a single author: Co-authored-by: and tool-session trailers fail the check.
  • History: commits before v2.9.0 were authored in batches and the history was rewritten, so their committer dates differ from their author dates.
  • Versions: SemVer. Breaking API changes bump the major version. Release notes go in CHANGELOG.md under the new version before tagging.
  • Database: never edit a released migration. Add the next number in backend/app/store.py; keep it additive (see Rollback in docs/ENVIRONMENTS.md).
  • Fab-specific behaviour belongs in a fab profile, not in code. See docs/ONBOARDING_A_FAB.md.
  • Solver changes: bump ENGINE_VERSION in backend/app/cache.py so cached plans from the old behaviour are never served, and re-run python -m scripts.benchmark to update docs/ANALYSIS.md.
  • Style: ruff (format + lint) for Python, ESLint for the frontend. Module docstrings explain why.

License

By contributing, you agree that your contribution is licensed under the project's MIT License. Adding a dependency? Check that its license is compatible and add it to THIRD_PARTY_NOTICES.md; a test fails until it's listed.

Releasing

See docs/ENVIRONMENTS.md: merge to main → verify in UAT → tag vX.Y.Z.