Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
73 lines (55 loc) · 2.57 KB

CONTRIBUTING.md

File metadata and controls

73 lines (55 loc) · 2.57 KB
Raw

Contributing to quantcortex

Development Setup

Use Python 3.11 through 3.14 from the repository root:

python3.11 -m venv .venv
.venv/bin/python -m pip install -r requirements/dev.lock
.venv/bin/python -m pip install --no-deps -e .

Run the required local checks before opening a pull request:

.venv/bin/ruff check .
.venv/bin/python -m pytest tests/ -q --cov=quantcortex --cov-fail-under=60
PYTHONPATH=. .venv/bin/python scripts/verify_brokers.py

Change Discipline

Keep changes within the existing pipeline boundaries. Preserve point-in-time data handling, allocation and exposure contracts, explicit transaction costs, paper-mode defaults, and fail-closed execution behavior. Changes to accounting, risk checks, order state, broker adapters, or causality require focused regression tests.

Do not commit credentials, account data, raw or cached market data, executed notebook outputs, local state, or generated reports. Published derived figures must include provenance and be regenerable from a permitted owner-supplied input identified by its digest.

Integration and Evidence Changes

Broker-adapter changes require the real SDK contract test in addition to the mock behavior script:

.venv/bin/python -m pip install -r requirements/brokers.lock
.venv/bin/python -m pytest tests/test_broker_sdk_conformance.py -q
PYTHONPATH=. .venv/bin/python scripts/verify_brokers.py

For report or paper changes, regenerate artifacts only from a permitted local input. Commit source changes first, then use scripts/release_paper_artifacts.sh so the manifest records a detached clean source revision. The wrapper also refreshes the reviewed docs/img/ performance gallery. Run the focused artifact tests and inspect every page of both the public and anonymous PDFs. Do not hand-edit generated tables, figures, manifests, or checksums. Use quantcortex.backtest.metrics.plotting for repository figures. Do not rely on color alone: pair important series with distinct line styles, markers, or hatching. Review paper figures at their final 5.5-inch text width and retain vector PDF output.

Dependencies

Edit pyproject.toml, then regenerate every lock artifact with:

scripts/update_dependency_locks.sh

Commit poetry.lock and all changed files under requirements/. CI rejects lock drift.

Pull Requests

Use short conventional commits such as fix: reconcile cash returns. A pull request should describe behavior, data and API assumptions, verification, and remaining limitations. Link relevant issues and include updated figures only when report output changes.