diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..b4e2645 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,74 @@ +name: Bug report +description: An ordersim run produced behavior that contradicts the documented model. +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time. This template is for cases where the + observed behavior diverges from what the docs or equivalence tests + claim. For open-ended questions, use + [Discussions](https://github.com/tradingexpert/ordersim/discussions) + instead. + - type: input + id: version + attributes: + label: ordersim version + description: Output of `pip show ordersim` or your editable install commit. + placeholder: "0.1.3" + validations: + required: true + - type: input + id: python + attributes: + label: Python version + placeholder: "3.11.7" + validations: + required: true + - type: input + id: platform + attributes: + label: Platform + placeholder: "macOS 14.5 arm64 / Ubuntu 22.04 x86_64 / ..." + validations: + required: true + - type: dropdown + id: engine + attributes: + label: Engine + description: Which engine produced the observation? + options: + - Python reference engine + - Compiled C++ engine + - Both (divergence between them) + - Not sure + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + description: What the documented model — or the other engine — would produce. + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + description: Event-stream excerpt, traceback, or other concrete observation. + render: text + validations: + required: true + - type: textarea + id: repro + attributes: + label: Minimal reproduction + description: Smallest snippet or fixture that exhibits the divergence. + render: python + validations: + required: true + - type: textarea + id: notes + attributes: + label: Anything else + description: Optional context, hypotheses, or links to related issues/discussions. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..f77e58a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Open-ended question or discussion + url: https://github.com/tradingexpert/ordersim/discussions + about: Conceptual questions, microstructure modeling debates, or anything not yet a concrete bug or feature. + - name: Editorial context + url: https://marketsinproduction.com/ordersim/ + about: The Markets in Production page for ordersim — positioning, scope, and the wider essay context. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..3cc7d08 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,43 @@ +name: Feature request +description: Propose a new capability, modeling primitive, or API addition. +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + ordersim aims for clarity per line of code over feature breadth. + Requests that fit the inspectable-execution-replay scope are + welcome; requests that turn this into a general backtester or a + live trading system are out of scope. + - type: textarea + id: problem + attributes: + label: What execution question would this answer? + description: | + Frame the proposal as the research or simulation question that + cannot currently be answered. "I want X" is harder to evaluate + than "I cannot currently tell whether Y happens because Z is not + modeled." + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed change + description: API surface, modeling primitive, or behavior you have in mind. + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: | + Workarounds you tried, related libraries, or reasons existing + primitives are not enough. + - type: checkboxes + id: scope + attributes: + label: Scope check + options: + - label: This is about inspectable execution replay (in scope). + - label: I have read the "What It Is Not" section of the README. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..0d8ad22 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,20 @@ + + +## What changed + + + +## Why + + + +## How it was checked + +- [ ] `pytest` passes locally. +- [ ] If this touches the matching engine: Python and C++ engines still produce identical event logs against the equivalence fixtures. +- [ ] If this changes observable behavior: a test fixture captures the new behavior. +- [ ] If this changes the public API: docstrings, examples, and `CHANGELOG.md` updated. + +## Notes for review + + diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..21ea0e4 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,77 @@ +# Roadmap + +This is a direction document, not a commitment. The dates are deliberately +omitted — the order of priorities is the useful information. Open issues and +discussions are the working surface; this file exists so a new reader can see +where the project is going without reading the whole tracker. + +## Near term — what's actively being shaped + +These are the questions that are likely to land first, in roughly the order +they will probably arrive. + +- **Maker–taker fee modeling.** See [#40](https://github.com/tradingexpert/ordersim/issues/40). + The fee model is currently a uniform schedule; venue-realistic maker/taker + separation is needed before fee-sensitive strategy comparisons become + honest. +- **Limit-order fill-connected strategies.** See [#39](https://github.com/tradingexpert/ordersim/issues/39). + Strategies that route their next action off the result of a fill — partial, + passive, or cancelled — are first-class research subjects. The gateway API + should make this ergonomic without leaking event-loop concerns into the + strategy code. +- **Engine equivalence depth.** The Python and C++ engines must produce + identical event logs against the equivalence fixtures. New fixtures are + added as new fill paths get exercised. Equivalence is a release gate, not + an aspiration. + +## Middle distance — directions, not commitments + +- **Venue-specific matching behavior.** See the open + [Discussion](https://github.com/tradingexpert/ordersim/discussions). The + honest version of this is not a "supports venue X" matrix but a small set + of named matching primitives (price–time, pro-rata, price improvement + variants) that can be composed to match real venues, with the residual + uncertainty stated. +- **Hidden-liquidity modeling.** See the open + [Discussion](https://github.com/tradingexpert/ordersim/discussions). The + unhelpful version of this is a tunable knob. The useful version is an + explicit assumption surface that a study can declare and a reviewer can + audit. +- **More batch-ingest paths through the C++ engine** for callers that own + the event loop, while keeping the audited per-event `Replay(...)` path as + the reference for valuation marks. +- **Examples that mirror Trading Reality essays.** Each essay that turns on + an execution mechanism should have a runnable companion in + `examples/`. The + [latency demo](examples/latency_demo.py) is the template; adverse + selection and queue-position essays are the natural next companions. + +## Out of scope — deliberately, not yet + +`ordersim` is a simulator. It will not turn into: + +- A general-purpose backtesting framework. You own the strategy loop. +- A live trading system or order-routing gateway. The Python-facing API is + shaped so a production gateway can mirror it; the bridging code is yours. +- A signal library or alpha repository. +- A speed-first HFT framework. Compiled speed is welcome only when it + preserves observable behavior. + +These exclusions are how the surface stays inspectable. + +## Editorial context + +The conceptual frame for why these choices were made — and why "what an +order did, in order, against this replay" is the unit of research — lives at +[Markets in Production](https://marketsinproduction.com/ordersim/) and the +[Trading Reality](https://www.tradingreality.com) publication. The roadmap +should be read alongside that context, not separately from it. + +## Contributing + +Open a [Discussion](https://github.com/tradingexpert/ordersim/discussions) +for anything that does not yet look like a concrete bug or feature. Issues +labeled +[`good first issue`](https://github.com/tradingexpert/ordersim/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) +are the lowest-friction entry points. See [CONTRIBUTING.md](CONTRIBUTING.md) +for the working agreement.