From c2430b7c329dd29edc73c2db569d0fa2329686bb Mon Sep 17 00:00:00 2001 From: Khizar Imran <75162994+KhizarImran@users.noreply.github.com> Date: Tue, 6 Oct 2026 23:12:50 +0100 Subject: [PATCH] Add contributor guidance, issue templates, and compatibility policy --- .github/ISSUE_TEMPLATE/bug_report.md | 39 ++++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 31 ++++++++ CHANGELOG.md | 4 ++ COMPATIBILITY.md | 65 +++++++++++++++++ CONTRIBUTING.md | 88 +++++++++++++++++++++++ README.md | 7 ++ ROADMAP.md | 37 ++++++++++ 7 files changed, 271 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 COMPATIBILITY.md create mode 100644 CONTRIBUTING.md create mode 100644 ROADMAP.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..b8a9d57 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,39 @@ +--- +name: Bug report +about: Report a reproducible FX simulation, installation, or reporting bug +title: "" +labels: "" +assignees: "" +--- + +## Problem +Describe the bug and the expected versus actual behavior. Include exact errors +or a traceback and hand-calculated expected results when relevant. + +## Environment +- backtestingfx version (or commit): +- Python version and interpreter: +- OS and architecture: +- pandas / numpy versions: +- Plotly version (if reporting): +- Installation method (wheel, source, development); Rust version if source-built: + +## Data and simulation settings +- Instrument, account currency, and quote-to-account conversion: +- Row count, column names/dtypes, and index type: +- Timeframe, timestamp format/unit, and timezone: +- OHLC price convention (midpoint, bid, or ask): +- Cash, lot sizes, contract size, spread, commission, and SL/TP settings: + +## Minimal reproduction +Provide a runnable code block that constructs a small synthetic DataFrame, +defines the strategy or signal function, and runs the failing call. Include +sample rows and output; avoid private data and external file dependencies. + +```python +# Imports, synthetic input, strategy/signals, settings, and failing call +``` + +## Additional context +Does this happen on the latest release or main? If it is a regression, include +the last working version and relevant logs. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..3c50c60 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,31 @@ +--- +name: Feature request +about: Propose an FX research capability or API improvement +title: "" +labels: "" +assignees: "" +--- + +## FX use case and problem +Describe the research workflow and what currently prevents it. + +## Proposed behavior +Give an API/code example and explain expected execution or result semantics. + +## Environment and representative data +- backtestingfx and Python versions; OS/architecture: +- Instrument, timeframe, row count, column/index types, and timestamp timezone/unit: +- Relevant sizing, costs, conversion, or order assumptions: + +## Current workaround +Include a small example of the current workflow if possible, and alternatives +you considered. + +## Acceptance criteria +List observable outcomes and edge cases that would make the feature complete. +Explain how the behavior could be tested with synthetic data. + +## Compatibility and scope +Could existing strategies or results change? Note any related +[roadmap](https://github.com/KhizarImran/backtestingfx/blob/main/ROADMAP.md) +items or issues. diff --git a/CHANGELOG.md b/CHANGELOG.md index 6e63f46..19644f8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,10 @@ ## [Unreleased] +### Added +- Contributor setup and validation guidance, bug/feature issue templates, an + API/platform compatibility policy, and a prioritized FX roadmap. + ### Fixed - `spread` now means the full bid–ask width around midpoint OHLC prices. Each fill applies half the width, so a one-pip EURUSD spread costs $10 per standard diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md new file mode 100644 index 0000000..b0adf84 --- /dev/null +++ b/COMPATIBILITY.md @@ -0,0 +1,65 @@ +# Compatibility policy + +## Python and platforms + +Package metadata declares Python >=3.9. CPython is the intended interpreter; +PyPy support is not currently verified. pandas and numpy are required. +HTML reporting additionally requires Plotly >=5 through the `report` extra. + +| Area | Current coverage | +| --- | --- | +| Functional CI | Ubuntu, CPython 3.12; Rust checks and installed-package Python tests | +| Linux release wheel targets | x86_64 and aarch64, with manylinux selected by maturin | +| macOS release wheel targets | Intel x86_64 and Apple Silicon aarch64 | +| Windows release wheel target | x64 | +| Source distributions | Built by the release workflow; require Rust and a native compiler to install | + +These wheel targets describe the configured release workflow, not a guarantee +that every Python version has a published wheel or has passed functional tests. +The extension does not currently use abi3, so wheel compatibility depends on +the interpreter and platform tags. Linux/macOS builds discover interpreters; +Windows explicitly selects Python 3.13. Check the artifacts for the release +and your interpreter before relying on wheel availability. + +If pip falls back to a source build, install a current stable Rust toolchain +and your platform's compiler/linker, then retry installation. Contributor +setup is in [CONTRIBUTING.md](CONTRIBUTING.md). Broader wheel verification and +functional coverage are tracked in issues +[#35](https://github.com/KhizarImran/backtestingfx/issues/35) and +[#36](https://github.com/KhizarImran/backtestingfx/issues/36). + +## Public API and stability + +The project is pre-1.0. Public Python imports from `backtestingfx`, documented +strategy methods/properties, result fields, and documented execution assumptions +are the compatibility surface. Underscore-prefixed members and internal Rust +implementation details may change; existing examples using private strategy +members do not make those members stable. + +Before 1.0, intentional incompatible API changes belong in a minor release +with a changelog entry and migration instructions. Patch releases should +preserve API signatures, but correctness fixes can change simulated fills, +PnL, equity, and statistics. Such changes must identify the previous and new +behavior and any migration required. After 1.0, intentional incompatible public +API changes require a major release. + +Where practical, deprecated Python APIs emit `DeprecationWarning` and remain +available for at least one minor release before removal. Document the +replacement and planned removal version. A correctness fix that cannot retain +the old behavior safely may be made without a deprecation period, with an +explicit explanation and migration notes. + +Changes to the minimum Python version or supported platform targets must be +announced in the changelog and this policy. Before 1.0 they belong in a minor +release; after 1.0 they require a major release. + +## Reproducibility + +Pin the library and dependency versions for reproducible research. Record data +source, instrument, timeframe, timezone, sizing, spread, commission, and +conversion assumptions. Read [CHANGELOG.md](CHANGELOG.md) before upgrading: +unchanged strategy code can produce different results after a modeling fix. +The full bid–ask spread correction in Unreleased is one such example. + +This policy describes project expectations; the current tests and published +artifacts establish the coverage actually verified for each release. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..cb6284c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,88 @@ +# Contributing + +backtestingfx focuses on FX research with OHLCV bars, lot sizing, spread, +commission, and quote-to-account conversion. See the [roadmap](ROADMAP.md) +for priorities and the [compatibility policy](COMPATIBILITY.md) 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: + +```bash +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: + +```bash +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. + +```bash +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: + +```bash +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. diff --git a/README.md b/README.md index 7f02b23..1682fed 100644 --- a/README.md +++ b/README.md @@ -270,6 +270,13 @@ The index should be a `DatetimeIndex`, or include a `timestamp` column. Volume i The backtesting engine is written in Rust and compiled as a native Python extension via [PyO3](https://pyo3.rs). This means the event loop, broker simulation, and stats computation run at native speed while your strategy stays in plain Python. +## Contributing and project direction + +See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, checks, and examples, +[COMPATIBILITY.md](COMPATIBILITY.md) for API and platform expectations, and +[ROADMAP.md](ROADMAP.md) for the FX scope and prioritized backlog. +Use the GitHub issue templates for bug reports and feature proposals. + ## License MIT — see [LICENSE](LICENSE) diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..df5907c --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,37 @@ +# FX scope and roadmap + +backtestingfx is an FX research library: Python strategies and vectorized +signals run against a Rust OHLCV simulation with lot sizing, spread, commission, +and quote-to-account conversion. Priorities focus on dependable simulation, +usable research APIs, and reproducible results. Live broker connectivity, +tick/order-book simulation, and general multi-asset portfolio accounting are +outside the current roadmap. + +This is a prioritized backlog, not a release-date commitment. Linked issues +contain acceptance criteria and current status; update this document when +priorities or delivered capabilities change. + +## 1. Correctness foundation (P0) + +- Gap-aware stop/target fills: [#8](https://github.com/KhizarImran/backtestingfx/issues/8). +- Data and timestamp validation: [#15](https://github.com/KhizarImran/backtestingfx/issues/15). +- Broker, size, and signal validation: [#16](https://github.com/KhizarImran/backtestingfx/issues/16). +- Independent native engine runs: [#18](https://github.com/KhizarImran/backtestingfx/issues/18). + +## 2. Core adoption (P1) + +- Explicit execution timing and intrabar assumptions: [#10](https://github.com/KhizarImran/backtestingfx/issues/10), [#11](https://github.com/KhizarImran/backtestingfx/issues/11). +- Margin, pending orders, and risk sizing: [#9](https://github.com/KhizarImran/backtestingfx/issues/9), [#24](https://github.com/KhizarImran/backtestingfx/issues/24), [#26](https://github.com/KhizarImran/backtestingfx/issues/26). +- Public strategy data, indicators, and parameters: [#19](https://github.com/KhizarImran/backtestingfx/issues/19), [#20](https://github.com/KhizarImran/backtestingfx/issues/20), [#21](https://github.com/KhizarImran/backtestingfx/issues/21). +- Result exports and accounting tests: [#32](https://github.com/KhizarImran/backtestingfx/issues/32), [#37](https://github.com/KhizarImran/backtestingfx/issues/37). +- Wheel coverage, platform CI, and API documentation: [#35](https://github.com/KhizarImran/backtestingfx/issues/35), [#36](https://github.com/KhizarImran/backtestingfx/issues/36), [#40](https://github.com/KhizarImran/backtestingfx/issues/40). + +## 3. Research usability and maturity (P2) + +- Optimization constraints and objectives: [#28](https://github.com/KhizarImran/backtestingfx/issues/28). +- Out-of-sample workflows and broader metrics: [#31](https://github.com/KhizarImran/backtestingfx/issues/31), [#33](https://github.com/KhizarImran/backtestingfx/issues/33). +- Fair benchmarks and practical tutorials: [#39](https://github.com/KhizarImran/backtestingfx/issues/39), [#41](https://github.com/KhizarImran/backtestingfx/issues/41). + +Browse the [full issue backlog](https://github.com/KhizarImran/backtestingfx/issues) +for additional work. Discuss larger API or modeling proposals in an issue before +implementation and state their FX use case.