gavindiaz/backtestingfx
1
0
Fork 0
mirror of https://github.com/KhizarImran/backtestingfx.git synced 2026-11-02 03:26:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #45 from KhizarImran/docs/42-contributing-and-compatibility

Browse Source 
Add contributor guidance, issue templates, and compatibility policy
This commit is contained in:
Khizar Imran
2026-10-06 23:14:03 +01:00
committed by GitHub
parent 72f715b95b c2430b7c32
commit 7c48e57af6
7 changed files with 271 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/ISSUE_TEMPLATE/bug_report.md
+39
View File
@@ -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.
.github/ISSUE_TEMPLATE/feature_request.md
+31
View File
@@ -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.
CHANGELOG.md
+4
View File
@@ -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
COMPATIBILITY.md
+65
View File
@@ -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.
CONTRIBUTING.md
+88
View File
@@ -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.
README.md
+7
View File
@@ -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)
ROADMAP.md
+37
View File
@@ -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.