|
| 1 | +# Repository Guidelines |
| 2 | + |
| 3 | +## Project Structure & Module Organization |
| 4 | +- Core trading code lives in `thetagang/`; the CLI entry point is `thetagang/entry.py`, with the main orchestration in `portfolio_manager.py` and configuration models |
| 5 | +in `config.py`. |
| 6 | +- Broker integrations and execution helpers sit in `thetagang/ibkr.py`, `orders.py`, and related utilities under the same package. |
| 7 | +- Supporting scripts and assets reside in `tws/`, `lib/`, and the packaging files `pyproject.toml` and `uv.lock`; sample configs and data are under `data/` and |
| 8 | +`thetagang.toml`. |
| 9 | +- Tests mirror the module layout inside `tests/`; fixtures and async helpers are centralized in `tests/conftest.py`. |
| 10 | + |
| 11 | +## Build, Test, and Development Commands |
| 12 | +- `uv run thetagang --config thetagang.toml --dry-run` — execute the bot without submitting live trades. |
| 13 | +- `uv run pytest` — run the full test suite; append a path (e.g., `tests/test_portfolio_manager.py`) to scope runs. |
| 14 | +- `uv run pytest --cov=thetagang` — gather coverage for trading logic changes. |
| 15 | +- `uv run ruff check .` / `uv run ruff format .` — lint and auto-format the codebase. |
| 16 | +- `uv run pyright` — perform static type checking. |
| 17 | +- `uv run pre-commit run --all-files` — replicate the CI hook set before pushing. |
| 18 | + |
| 19 | +## Coding Style & Naming Conventions |
| 20 | +- Python ≥3.10 with 4-space indentation and Ruff-enforced 88 character lines; keep imports sorted via Ruff. |
| 21 | +- Use snake_case for functions and variables, CapWords for classes, and descriptive config keys; follow existing naming inside `portfolio_manager.py`. |
| 22 | +- Annotate new or modified functions with precise type hints and keep module-level constants uppercase. |
| 23 | +- Add configuration-driven behavior through Pydantic models in `config.py`, ensuring defaults and validation match `thetagang.toml`. |
| 24 | + |
| 25 | +## Testing Guidelines |
| 26 | +- Tests rely on `pytest` and `pytest-asyncio`; name files `test_<module>.py` and prefer async tests for IBKR flows. |
| 27 | +- Stub external calls with fixtures from `tests/` to prevent network usage; extend them when adding API paths. |
| 28 | +- Cover edge cases for buy/sell-only rebalancing and order routing when adjusting portfolio logic. |
| 29 | +- Run `uv run pytest --cov=thetagang` before submitting changes and ensure new features include targeted assertions. |
| 30 | + |
| 31 | +## Commit & Pull Request Guidelines |
| 32 | +- Follow the conventional commit style seen in history (`fix:`, `feat:`, `chore:`) with optional scopes (`fix(portfolio): enforce buy-only thresholds`). |
| 33 | +- Keep subject lines in present tense ≤72 characters and use bodies to explain intent, risk, and testing evidence. |
| 34 | +- Rebase or squash noisy work-in-progress commits prior to open PRs. |
| 35 | +- PR descriptions should note behavioral impacts, list validation commands, link issues, and include relevant logs or screenshots for trading output adjustments. |
0 commit comments