Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
70 lines (55 loc) · 2.87 KB

CONTRIBUTING.md

File metadata and controls

70 lines (55 loc) · 2.87 KB
Raw

Contributing to cortex-score

Thanks for your interest. This is a small, focused scientific package; the bar is honest provenance, correct numerics, and a green gate.

Development setup

git clone https://github.com/madhavcodez/cortex-score
cd cortex-score
python -m venv .venv && . .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev,cli]"

The base install is CPU-only (numpy + pydantic + platformdirs). The full score() path needs the GPU stack - see docs/install-gpu.md.

The gate (run before opening a PR)

ruff check src tests
ruff format --check src tests
mypy src                       # config is strict=true
pytest -m "not slow and not gpu" --cov=cortex_score --cov-report=term-missing
pytest tests/integration/test_packaging.py -m slow   # build + twine + wheel contents
  • Coverage must not drop below 80% (it currently sits well above).
  • import cortex_score must stay torch-free: heavy ML deps load lazily inside runners. tests/integration/test_score_import.py guards this.
  • GPU-only code lives behind @pytest.mark.gpu and is exercised by examples/modal_smoke.py.

Hard rules

  • Schema discipline. SCHEMA_VERSION in src/cortex_score/schemas.py is a contract. Any field add/remove/rename/relaxation → bump it, regenerate tests/fixtures/schema_v1.json and tests/fixtures/score_result_v1.json, and document it in CHANGELOG.md. The JSON schema_version is independent of the package version.
  • No scientific overclaiming. The 5-network rollup is a product grouping, not canonical neuroscience (see docs/interpretation.md). The "Not a brain scan / does not measure real viewer engagement" framing must survive everywhere.
  • No fabricated numbers. Benchmark/cost figures in docs must come from a real, reproducible run (e.g. benchmarks/bench_aggregate.py, examples/modal_smoke.py).
  • Reproducible provenance. result_id must remain verifiable from the serialized JSON alone (compute_result_id).

Commits & PRs

  • Conventional commits: feat:, fix:, refactor:, docs:, test:, build:, chore:, perf:, ci:. Explain why, not just what.
  • Keep PRs focused. Update CHANGELOG.md under [Unreleased].

Adding an encoder

Implement the PredictionRunner protocol (model_id, model_revision, predict_video) and return a PredictionBundle on fsaverage5. See cortex_score.runners.replay.ReplayRunner for a minimal, torch-free example.

Release

Versions are git-tag driven (hatch-vcs). Cutting a release means: move [Unreleased] notes into a dated section, bump CITATION.cff version/date-released to match (a test enforces this), then push a vX.Y.Z tag - the release workflow builds and publishes to PyPI via OIDC trusted publishing. See SECURITY.md for the supply-chain posture.