|
| 1 | +# Contributor Setup and Issue Filing |
| 2 | + |
| 3 | +How to set a working copy up for contribution, and how to file an issue. |
| 4 | +Human-readable equivalent: root `CONTRIBUTING.md` (same steps, same order). |
| 5 | + |
| 6 | +## Set Up as a Contributor |
| 7 | + |
| 8 | +1. Get a working copy. External contributors fork on GitHub and clone the |
| 9 | + fork; maintainers branch directly off `master`: |
| 10 | + |
| 11 | + ```bash |
| 12 | + git clone https://github.com/<you>/quant-mind.git && cd quant-mind |
| 13 | + git checkout -b <type>/<short-topic> # e.g. feat/sec-collection |
| 14 | + ``` |
| 15 | + |
| 16 | +2. Create the environment with [uv](https://github.com/astral-sh/uv): |
| 17 | + |
| 18 | + ```bash |
| 19 | + uv venv && source .venv/bin/activate |
| 20 | + uv pip install -e ".[dev]" |
| 21 | + ``` |
| 22 | + |
| 23 | +3. Install the git hooks (pre-commit lint/format stage plus the pre-push |
| 24 | + verify stage): |
| 25 | + |
| 26 | + ```bash |
| 27 | + ./scripts/pre-commit-setup.sh |
| 28 | + ``` |
| 29 | + |
| 30 | +4. Confirm the checkout is green before changing anything: |
| 31 | + |
| 32 | + ```bash |
| 33 | + bash scripts/verify.sh |
| 34 | + ``` |
| 35 | + |
| 36 | + Verify is the single deterministic gate — format, lint, types, import |
| 37 | + boundaries, tests with coverage. CI runs the exact same script, so a green |
| 38 | + local run means a green PR. If it fails on a fresh checkout, stop and report |
| 39 | + that instead of working around it. |
| 40 | + |
| 41 | +5. Continue with the workflow references: `develop-components.md` before |
| 42 | + writing code, then `commit.md` and `pull-request.md`. |
| 43 | + |
| 44 | +## File an Issue |
| 45 | + |
| 46 | +1. Requires an authenticated GitHub CLI (`gh auth status`; if missing, ask the |
| 47 | + user to run `gh auth login` themselves). |
| 48 | +2. Pick the shape that matches the request: |
| 49 | + - Defect in existing behavior → `.github/ISSUE_TEMPLATE/bug_report.md` |
| 50 | + - Missing source, knowledge type, flow, or capability → |
| 51 | + `.github/ISSUE_TEMPLATE/feature_request.md` |
| 52 | +3. Write the body in English following `contexts/dev/github-writing.md` |
| 53 | + (no hard-wrapping), and apply labels per `contexts/dev/labels.md`. |
| 54 | +4. Search for duplicates first (`gh issue list --search "<keywords>"`), then: |
| 55 | + |
| 56 | + ```bash |
| 57 | + gh issue create --title "<imperative summary>" --body-file <tmpfile> \ |
| 58 | + --label "<label>" |
| 59 | + ``` |
| 60 | + |
| 61 | +5. If the need came out of work in progress, link the issue from the related |
| 62 | + branch or PR so the discussion has code context. |
| 63 | + |
| 64 | +## Boundaries |
| 65 | + |
| 66 | +- Setup here targets contributing to QuantMind itself. Library-only users can |
| 67 | + stop after `uv pip install -e .` and do not need hooks. |
| 68 | +- Do not file issues that encode product decisions as settled; state the need |
| 69 | + and let maintainer discussion pick the design (see SKILL.md Boundaries). |
0 commit comments