Add contributor guidance, issue templates, and compatibility policy

.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.

.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.

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

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.

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.

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)

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.