Skip to content

Commit 5dda619

Browse files
author
QuantTradeAI Maintainer
committed
docs: add AGENTS.md and CONTRIBUTING.md; add PR/Issue templates\n\nchore(ci): remove duplicate pre-commit workflow in favor of existing ci.yml\n\nchore(readme): link to CONTRIBUTING.md
1 parent c8fd825 commit 5dda619

File tree

5 files changed

+406
-232
lines changed

5 files changed

+406
-232
lines changed

‎.github/ISSUE_TEMPLATE/pre-commit-ci.yml‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
name: "CI: Run pre-commit on PRs"
2+
description: Add GitHub Actions workflow to run pre-commit checks on pull requests.
3+
title: "CI: run pre-commit on PRs"
4+
labels: ["ci", "enhancement"]
5+
assignees: []
6+
body:
7+
- type: markdown
8+
attributes:
9+
value: |
10+
This task adds a GitHub Actions workflow that runs `pre-commit` on every pull request to ensure formatting, linting, and tests (as configured) pass before merge.
11+
12+
- type: checkboxes
13+
id: acceptance
14+
attributes:
15+
label: Acceptance Criteria
16+
options:
17+
- label: Workflow triggers on `pull_request` and `push` to default branch
18+
required: false
19+
- label: Uses Python 3.11 and Poetry to install dependencies
20+
required: false
21+
- label: Runs `poetry run pre-commit run --all-files`
22+
required: false
23+
- label: Fails the job on any hook failure
24+
required: false
25+
26+
- type: textarea
27+
id: plan
28+
attributes:
29+
label: Implementation Plan
30+
description: Suggested steps to implement the workflow.
31+
value: |
32+
1. Create `.github/workflows/pre-commit.yml` with the following:
33+
```yaml
34+
name: pre-commit
35+
on:
36+
pull_request:
37+
push:
38+
branches: [ main, master ]
39+
jobs:
40+
run:
41+
runs-on: ubuntu-latest
42+
steps:
43+
- uses: actions/checkout@v4
44+
- uses: actions/setup-python@v5
45+
with:
46+
python-version: '3.11'
47+
- name: Install Poetry
48+
run: |
49+
pipx install poetry
50+
- name: Install dependencies
51+
run: |
52+
poetry install --with dev
53+
- name: Run pre-commit
54+
run: |
55+
poetry run pre-commit run --all-files
56+
```
57+
2. Verify the workflow passes on an example PR.
58+
3. Optionally add a status badge to `README.md`.
59+
60+
- type: textarea
61+
id: context
62+
attributes:
63+
label: Additional Context
64+
description: Link related PRs or notes.
65+
validations:
66+
required: false
67+

‎.github/pull_request_template.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
## Summary
2+
3+
Describe the problem and the proposed solution in 1–3 sentences.
4+
5+
## Changes
6+
7+
- Key change 1
8+
- Key change 2
9+
10+
## Testing
11+
12+
- Commands run: `pytest -q`, `make lint`, `make format-check`
13+
- Coverage or critical paths touched:
14+
15+
## Screenshots / Metrics (if applicable)
16+
17+
Attach logs, figures, or before/after metrics (e.g., Sharpe, accuracy).
18+
19+
## Breaking Changes
20+
21+
- [ ] No breaking changes
22+
- Details if any:
23+
24+
## Checklist
25+
26+
- [ ] Added/updated tests
27+
- [ ] Ran `pre-commit run --all-files`
28+
- [ ] Updated docs/CLI help if needed
29+
- [ ] Linked related issues
30+

‎AGENTS.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Repository Guidelines
2+
3+
## Project Structure & Module Organization
4+
- Code lives in `quanttradeai/` (CLI in `quanttradeai/main.py`): `data/`, `features/`, `models/`, `backtest/`, `trading/`, `streaming/`, `utils/`.
5+
- Config files in `config/` (e.g., `model_config.yaml`, `backtest_config.yaml`).
6+
- Tests mirror the package in `tests/` (e.g., `tests/models/`, `tests/streaming/`).
7+
- Datasets and cache in `data/`; trained artifacts in `models/`; docs in `docs/`.
8+
9+
## Build, Test, and Development Commands
10+
- Install dev deps: `poetry install --with dev`
11+
- Format code: `make format` (Black)
12+
- Lint code: `make lint` (Flake8)
13+
- Run tests: `make test` or `poetry run pytest`
14+
- Run pipeline: `make pipeline` or `poetry run quanttradeai train -c config/model_config.yaml`
15+
- CLI help: `poetry run quanttradeai --help`
16+
- Package build (optional): `poetry build`
17+
18+
## Coding Style & Naming Conventions
19+
- Python 3.11+, format with Black (line length 88). Lint via Flake8 (ignores: E203, W503, etc. per `.flake8`).
20+
- Naming: snake_case (functions/vars), PascalCase (classes), UPPER_SNAKE_CASE (constants). Files: `snake_case.py`.
21+
- Tests named `test_*.py`; keep public imports curated in `quanttradeai/__init__.py`.
22+
- Avoid unused imports/variables; prefer pure, side‑effect‑free helpers in `utils/`.
23+
24+
## Testing Guidelines
25+
- Framework: Pytest. Place unit tests under matching folders in `tests/`.
26+
- Conventions: files `test_<unit>.py`, tests `test_<behavior>`; use fixtures/mocks for I/O, streaming, and external APIs.
27+
- Cover edge cases: NaNs/gaps in data, feature windows, execution costs/slippage, websocket disconnects.
28+
- Run locally: `pytest -q` or `make test`.
29+
30+
## Commit & Pull Request Guidelines
31+
- Use Conventional Commits (e.g., `feat(backtest): add execution cost modelling`, `test: cover streaming safeguards`).
32+
- PRs include: clear description, linked issues, CLI/API changes, before/after metrics or plots when relevant, and tests for new behavior.
33+
- Ensure `pre-commit run --all-files` (format, lint, test) passes before requesting review.
34+
35+
## Security & Configuration Tips
36+
- Keep secrets in env vars (e.g., `OPENAI_API_KEY`); never commit `.env`.
37+
- Centralize knobs in YAML under `config/`; validate changes with `verify_config_loading.py`.
38+
- Write outputs to `data/`, `models/`, `reports/` (these paths are gitignored by default).
39+

‎CONTRIBUTING.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Contributing to QuantTradeAI
2+
3+
Thanks for your interest in contributing! This guide covers setup, workflow, and review expectations.
4+
5+
## Setup
6+
- Prerequisites: Python 3.11+, Poetry.
7+
- Install deps: `poetry install --with dev`
8+
- Install hooks: `poetry run pre-commit install`
9+
10+
## Development Workflow
11+
1. Create a feature branch: `git checkout -b feat/<scope>-<short-desc>`
12+
2. Write code and tests under `quanttradeai/` and `tests/` (mirror structure).
13+
3. Run quality gates locally:
14+
- Format: `make format`
15+
- Lint: `make lint`
16+
- Test: `make test`
17+
4. Optional: quick sanity run
18+
- CLI help: `poetry run quanttradeai --help`
19+
- Pipeline: `poetry run quanttradeai train -c config/model_config.yaml`
20+
21+
## Style & Conventions
22+
- Formatting: Black (line length 88); lint: Flake8 (see `.flake8`).
23+
- Naming: snake_case for functions/vars, PascalCase for classes, UPPER_SNAKE_CASE for constants.
24+
- Commits: Conventional Commits, e.g. `feat(backtest): add execution cost modelling`, `test: cover streaming safeguards`.
25+
26+
## Pull Requests
27+
- Template: PRs auto-use `.github/pull_request_template.md`.
28+
- Include: clear summary, list of changes, tests, and any screenshots/metrics when relevant.
29+
- Ensure `pre-commit run --all-files` passes before requesting review.
30+
31+
## Configuration & Secrets
32+
- Keep credentials in env vars (e.g., `OPENAI_API_KEY`); do not commit `.env`.
33+
- Use YAML in `config/` to change behavior; validate with `verify_config_loading.py` if modified.
34+
35+
## Getting Help
36+
- Check `README.md` and `docs/` for usage details.
37+
- Open a GitHub Discussion/Issue with a minimal repro if blocked.
38+

0 commit comments

Comments
 (0)