docs: add open source contribution guidelines

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,50 @@
+---
+name: Bug report
+about: Report a reproducible QuantBT bug
+title: "bug: "
+labels: bug
+assignees: ""
+---
+
+## Summary
+
+What happened?
+
+## Reproduction
+
+Minimal code or notebook cell:
+
+```python
+
+```
+
+## Environment
+
+- QuantBT commit:
+- Python version:
+- OS:
+- Optional backend, if any:
+
+## Backtest Configuration
+
+- endpoint/backend:
+- symbol/timeframe/date range:
+- sizing mode:
+- `use_pyramiding`:
+- initial capital:
+- leverage:
+- fee/slippage/funding:
+- margin/liquidation settings:
+
+## Expected Result
+
+What should happen?
+
+## Actual Result
+
+What happened instead?
+
+## First Divergence
+
+If comparing engines, provide the first timestamp where equity, position, fill,
+cash, or fee differs.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Contribution guide
+    url: https://github.com/BobbyAxerol/quantbt/blob/dev/CONTRIBUTING.md
+    about: Read the workflow, branch policy, and testing expectations.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,27 @@
+---
+name: Feature request
+about: Suggest a new QuantBT capability
+title: "feat: "
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+What research or backtest workflow is currently hard?
+
+## Proposed Solution
+
+Describe the behavior you want.
+
+## Backtest Domain
+
+- strategy family: single order, grid/DCA, pair, portfolio, market neutral, etc.
+- signal/input contract:
+- execution model:
+- accounting requirements:
+- expected speed requirements:
+
+## Alternatives
+
+What other approaches did you consider?

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,40 @@
+## Summary
+
+Describe what changed and why.
+
+## Type
+
+- [ ] Bug fix
+- [ ] Feature
+- [ ] Engine/accounting change
+- [ ] Nautilus parity change
+- [ ] Documentation
+- [ ] Tests
+
+## Backtest Assumptions
+
+If this changes engine behavior, document:
+
+- signal contract:
+- sizing mode:
+- execution/fill timing:
+- fee/slippage/funding model:
+- margin/leverage/liquidation behavior:
+- portfolio/netting behavior:
+
+## Tests
+
+Paste the commands run:
+
+```bash
+
+```
+
+## Checklist
+
+- [ ] This PR targets `dev`.
+- [ ] I did not commit directly to `main`.
+- [ ] The change is scoped to one topic.
+- [ ] Tests or reproducible validation are included.
+- [ ] Documentation/examples are updated if public behavior changed.
+- [ ] No unrelated files are included.

.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [dev]
+  push:
+    branches: [dev]
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    name: Python tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -U pip
+          python -m pip install numpy pandas numba matplotlib seaborn pytest
+
+      - name: Run core tests
+        env:
+          PYTHONPATH: ${{ github.workspace }}/..
+        run: |
+          pytest tests \
+            --ignore=tests/test_real.py \
+            --ignore=tests/test_real_endpoints.py \
+            --ignore=tests/test_phase5_nautilus_adapter.py

CODE_OF_CONDUCT.md

@@ -0,0 +1,27 @@
+# Code of Conduct
+
+QuantBT is a technical research project. We want discussions to stay direct,
+curious, and useful.
+
+## Expected Behavior
+
+- Be respectful and constructive.
+- Critique assumptions, code, and tests rather than people.
+- Explain financial, statistical, or engineering claims with reproducible
+  examples when possible.
+- Make room for contributors with different experience levels.
+- Keep disagreements focused on evidence and project goals.
+
+## Unacceptable Behavior
+
+- Harassment, threats, insults, or discriminatory language.
+- Publishing private information without permission.
+- Repeated off-topic disruption.
+- Misrepresenting backtest results, benchmarks, or risk assumptions.
+
+## Enforcement
+
+Maintainers may edit, hide, or remove comments; close issues or pull requests;
+or block contributors who repeatedly violate these standards.
+
+If you see a problem, contact the maintainers through GitHub.

CONTRIBUTING.md

@@ -0,0 +1,143 @@
+# Contributing to QuantBT
+
+Thanks for helping make QuantBT faster, clearer, and easier to trust.
+
+QuantBT is a research-first backtesting package, but changes must still be
+reviewable and reproducible. The most valuable contributions are precise bug
+reports, parity tests, execution-model improvements, documentation, examples,
+and small well-tested engine changes.
+
+## Branch Policy
+
+- Use `dev` for all active work.
+- Do not commit directly to `main`.
+- Open pull requests into `dev`.
+- `main` is reserved for protected, reviewed releases.
+- Keep pull requests focused. Avoid mixing engine logic, docs, notebooks, and
+  formatting-only changes in one PR.
+
+## Development Setup
+
+Clone the repository and work from the QuantBT root:
+
+```bash
+git clone https://github.com/BobbyAxerol/quantbt.git
+cd quantbt
+git checkout dev
+```
+
+Install the core development dependencies:
+
+```bash
+python -m pip install -U pip
+python -m pip install numpy pandas numba matplotlib seaborn pytest
+```
+
+Optional Nautilus validation support:
+
+```bash
+python -m pip install nautilus-trader
+```
+
+When working inside the broader research workspace, use the parent environment
+and set `PYTHONPATH` so imports resolve consistently:
+
+```bash
+PYTHONPATH=/path/to/pool_alpha pytest quantbt/tests
+```
+
+## Contribution Workflow
+
+1. Create a feature branch from `dev`.
+
+```bash
+git checkout dev
+git pull
+git checkout -b feature/clear-short-name
+```
+
+2. Make the smallest coherent change.
+3. Add or update tests for behavior changes.
+4. Update docs or examples when the public API, sizing semantics, margin model,
+   or fill policy changes.
+5. Run the relevant test set.
+6. Open a pull request into `dev`.
+
+## Testing Expectations
+
+Use the smallest test set that proves the change, then expand when touching
+shared engine behavior.
+
+```bash
+pytest tests/test_endpoint.py
+pytest tests/test_phase2_native_vectorized.py
+pytest tests/test_phase3_native_event.py
+pytest tests/test_phase5_nautilus_adapter.py
+```
+
+For changes to accounting, sizing, margin, liquidation, fees, funding, or
+Nautilus parity, include at least one deterministic test with a small synthetic
+dataset. Real-data tests are useful for smoke checks, but they should not be the
+only proof.
+
+## Backtest Engine Rules
+
+Please make assumptions explicit. A good engine change should document:
+
+- signal contract: raw weight, target unit, target notional, structural ladder,
+  or explicit order intent;
+- execution timing: close fill, next-bar fill, high/low limit touch, or
+  event-driven order fill;
+- cost model: fee convention, slippage, funding, borrow, spread, and turnover;
+- account model: cash, equity, initial margin, buying power, leverage,
+  maintenance margin, and liquidation;
+- position model: one-way/netting, long-short, pyramiding, portfolio netting, or
+  market-neutral constraints.
+
+If two engines intentionally differ, add a parity note or test that explains
+why.
+
+## Code Style
+
+- Prefer clear, small functions over clever abstractions.
+- Keep vectorized/Numba kernels deterministic and allocation-light.
+- Avoid hidden global state in engines and adapters.
+- Keep public endpoint behavior stable unless the PR is explicitly a breaking
+  change.
+- Add comments only where they clarify non-obvious domain logic.
+
+## Pull Request Checklist
+
+Before opening a PR, confirm:
+
+- The PR targets `dev`.
+- The change is scoped to one topic.
+- Tests were run and the command is included in the PR.
+- New behavior is documented.
+- Engine assumptions are explicit.
+- No unrelated dirty files are included.
+
+## Commit Messages
+
+Use concise imperative commit messages:
+
+```text
+fix: align nautilus pct equity sizing
+feat: add dca ladder limit fill audit
+docs: explain margin buying power
+test: cover portfolio netting modes
+```
+
+## Reporting Backtest Differences
+
+When reporting that two backtests differ, include:
+
+- data range, timeframe, symbol, and row count;
+- endpoint/backend used;
+- sizing mode and `use_pyramiding`;
+- initial capital, leverage, margin settings;
+- fee, slippage, funding configuration;
+- expected vs actual metrics;
+- first timestamp where equity, position, fill, or cash diverges.
+
+This makes the difference debuggable instead of mysterious.

SECURITY.md

@@ -0,0 +1,31 @@
+# Security Policy
+
+QuantBT is a backtesting and research package. Security issues can still matter,
+especially around data loading, file export, notebooks, optional dependencies,
+and external engine adapters.
+
+## Reporting a Vulnerability
+
+Please do not open a public issue for a suspected security vulnerability.
+
+Report it privately through GitHub Security Advisories when available, or
+contact the maintainer through GitHub with:
+
+- affected version or commit;
+- reproduction steps;
+- expected impact;
+- suggested mitigation, if known.
+
+## Scope
+
+Security reports may include:
+
+- arbitrary file writes or path traversal;
+- unsafe deserialization;
+- dependency-related vulnerabilities;
+- credential leakage in examples, configs, logs, or notebooks;
+- unsafe behavior in adapters or data loaders.
+
+Backtest result differences, financial losses, strategy performance, and market
+risk are not security vulnerabilities. Please report those as regular bugs with
+a reproducible example.

SUPPORT.md

@@ -0,0 +1,18 @@
+# Support
+
+Use GitHub issues for reproducible bugs, feature requests, and documentation
+gaps.
+
+For backtest result differences, include a small dataset or synthetic example
+when possible. At minimum, include:
+
+- endpoint/backend;
+- symbol, timeframe, and date range;
+- signal contract and sizing mode;
+- fee, slippage, funding, leverage, and margin settings;
+- expected result;
+- actual result;
+- first timestamp where the run diverges, if known.
+
+Questions about strategy profitability, investment advice, or live trading
+decisions are outside the support scope of this repository.