backtestingfx/CONTRIBUTING.md

Contributing

backtestingfx focuses on FX research with OHLCV bars, lot sizing, spread, commission, and quote-to-account conversion. See the roadmap for priorities and the compatibility policy before changing public behavior. Search existing issues before opening a bug or feature request.

Local setup

Install Git, CPython 3.9 or newer, and a current stable Rust toolchain with Cargo and Clippy. The crate uses Rust edition 2024 (Rust 1.85 or newer); dependency requirements may require a newer compiler. Python 3.12 on Linux matches the current CI configuration. Building the extension also requires your platform's native compiler/linker (for example, Xcode Command Line Tools on macOS or MSVC Build Tools on Windows).

From your clone's root:

git clone https://github.com/KhizarImran/backtestingfx.git
cd backtestingfx
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "maturin>=1.0,<2.0" pandas numpy "plotly>=5"
maturin develop

On Windows, activate with .venv\Scripts\Activate.ps1 in PowerShell instead. Use your virtual environment's Python for all commands. Run maturin develop again after Rust changes. Python source changes are visible through the development installation.

Checks

Run the Rust checks from the repository root:

cargo clippy --all-targets -- -D warnings
cargo test

Check the installed Python package outside the source directory, as CI does. This avoids accidentally importing the source package without its built extension.

python -m pip install ".[report]"
repo_dir="$PWD"
cd /tmp
python -m unittest discover -s "$repo_dir/tests"
cd "$repo_dir"

On Windows, save the repository path, change to a temporary directory, and pass the absolute path to tests to python -m unittest discover -s. Reinstall with python -m pip install --force-reinstall ".[report]" after changes when using this regular installation rather than maturin develop.

Examples

Run these from the repository root after building/installing the package:

python examples/sma_cross.py
python examples/optimize.py
python examples/html_report.py
cargo run --example simple_strategy

SMA and optimization examples use the included data/EURUSD_1H.csv. The HTML example generates synthetic data, writes backtestingfx-report.html, and attempts to open a browser. It requires the report extra. Comparison and benchmark scripts additionally require python -m pip install backtesting; report their versions and execution assumptions when sharing results.

Pull requests

Create a focused branch and describe the problem, resulting behavior, and validation performed. Link the relevant issue using Closes #number when the PR completes it. For behavior changes, add regression tests with small, deterministic inputs and update documentation and the Unreleased changelog. Explain intentional changes to fills, costs, timestamps, or statistics and include migration guidance when existing results can change.

Use the bug template to report versions, input shape and timestamps, broker settings, expected versus actual results, and a minimal runnable reproduction. Use synthetic or shareable data rather than private trading records.