Contributing

Tests: always run via tools/test.sh (Linux/macOS) or tools/test.ps1 (Windows). These are the only supported entrypoints and they fail fast if your environment is non-deterministic.

1. Fork → python -m pip install -e ".[dev]".
2. Run tools/test.sh -q (Windows: powershell -ExecutionPolicy Bypass -File tools/test.ps1 -q).
3. Open a PR with:
   • Tests for new features (especially schema/viz contracts).
   • Docs updates (README + relevant markdown here; public website copy lives in ~/Helix-WebSite).
   • CHANGELOG.md entry.

For a fast Studio/Qt regression pass on Linux/macOS, run QT_QPA_PLATFORM=offscreen bash tools/studio_smoke.sh. On Nix hosts with ./.venv-helix, prefer tools/test.sh or tools/studio_smoke.sh over direct python -m pytest; the canonical runner now resolves the Qt/PySide runtime library path automatically.

Schema or viz changes should include manifest diffs and sample artifacts (helix demo viz) so reviewers can verify provenance.

If anything about your environment feels “haunted”, run python tools/doctor.py and include the output in the issue/PR.

CI policy

CI is intentionally budget-capped: expensive lanes are opt-in and workflow files are treated as money controls. See docs/dev/ci_policy.md.

Dependency pinning policy

The plotting stack (matplotlib, python-dateutil) is pinned because it can fail silently across environments (most commonly via matplotlib ↔ python-dateutil version mismatches caused by system site-package leakage); bump these pins only in a dedicated “deps bump” PR that runs the full CI matrix so we keep deterministic, reproducible test behavior.

Schema compatibility policy

Schema changes must follow the v1.x compatibility contract documented in docs/concepts/schemas.md.