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.

Fork → python -m pip install -e ".[dev]".
Run tools/test.sh -q (Windows: powershell -ExecutionPolicy Bypass -File tools/test.ps1 -q) plus mkdocs serve to preview docs.
Open a PR with:
- Tests for new features (especially schema/viz contracts).
- Docs updates (README + MkDocs page).
- CHANGELOG.md entry.

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.