docs: add CONTRIBUTING.md, issue templates, and contribution roadmap

- CONTRIBUTING.md with dev setup, code standards, and difficulty-tiered roadmap - GitHub issue templates (bug report + feature request) with YAML forms - README: add Contributing section with contribution areas table
2026-04-10 16:17:19 +08:00
1 parent 10a3027b7a
commit 6446477988
@@ -0,0 +1,77 @@
+name: Bug Report
+description: Report a bug or unexpected behavior
+title: "[Bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting! Please fill out the sections below.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened? What did you expect to happen?
+      placeholder: |
+        **What happened:**
+        The backtest command crashed with a KeyError.
+
+        **What I expected:**
+        The backtest should complete and show results.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: How can we reproduce this?
+      placeholder: |
+        1. Run `vibe-trading run -p "Backtest BTC-USDT MACD strategy"`
+        2. Wait for backtest to complete
+        3. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error Logs
+      description: Paste any error messages or stack traces
+      render: shell
+
+  - type: dropdown
+    id: interface
+    attributes:
+      label: Interface
+      description: How are you using Vibe-Trading?
+      options:
+        - CLI (vibe-trading)
+        - Web UI (vibe-trading serve)
+        - MCP Plugin
+        - Docker
+        - Python API
+    validations:
+      required: true
+
+  - type: input
+    id: provider
+    attributes:
+      label: LLM Provider
+      description: Which provider are you using?
+      placeholder: "e.g., openrouter, deepseek, ollama"
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: "Run `pip show vibe-trading-ai` to check"
+      placeholder: "e.g., 0.1.3"
+
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: OS and Python version
+      placeholder: "e.g., macOS 15 / Python 3.11"
@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Discord Community
+    url: https://discord.gg/2vDYc2w5
+    about: Ask questions, share strategies, get help
+  - name: Documentation
+    url: https://github.com/HKUDS/Vibe-Trading#-quick-started
+    about: Check the README for setup and usage guides
@@ -0,0 +1,62 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+title: "[Feature] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for your idea! Please describe what you'd like.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or Motivation
+      description: What problem does this solve? Why do you need it?
+      placeholder: |
+        I often need to compare multiple strategies side by side,
+        but currently I have to run them one at a time.
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: How would you like it to work?
+      placeholder: |
+        Add a `/compare` command that takes multiple run IDs
+        and shows a side-by-side performance table.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      description: Which part of the project does this affect?
+      options:
+        - Skills (new finance skill)
+        - Backtest (engines, loaders, metrics)
+        - Swarm (new preset or workflow)
+        - CLI / TUI
+        - Web UI
+        - MCP Plugin
+        - Data Sources
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any other approaches you've thought about?
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      options:
+        - label: I'm willing to submit a PR for this feature
@@ -0,0 +1,169 @@
+# Contributing to Vibe-Trading
+
+Thanks for your interest in contributing! This guide will help you get started.
+
+## Quick Links
+
+- [Discord](https://discord.gg/2vDYc2w5) — ask questions, discuss ideas
+- [Issues](https://github.com/HKUDS/Vibe-Trading/issues) — bug reports & feature requests
+- [Good First Issues](https://github.com/HKUDS/Vibe-Trading/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — great starting points
+
+## Development Setup
+
+```bash
+git clone https://github.com/HKUDS/Vibe-Trading.git
+cd Vibe-Trading
+python -m venv .venv
+source .venv/bin/activate      # Linux/macOS
+# .venv\Scripts\Activate.ps1   # Windows
+
+pip install -e ".[dev]"
+cp agent/.env.example agent/.env
+# Edit agent/.env — set your LLM provider
+```
+
+### Run tests
+
+```bash
+pytest --ignore=agent/tests/e2e_backtest --tb=short -q
+```
+
+### Start dev servers
+
+```bash
+# Terminal 1: API server
+vibe-trading serve --port 8899
+
+# Terminal 2: Frontend
+cd frontend && npm install && npm run dev
+```
+
+## Project Structure
+
+| Directory | What lives here | Open to contribute? |
+|-----------|----------------|:-------------------:|
+| `agent/src/skills/` | 68 finance skill definitions (SKILL.md) | Yes |
+| `agent/src/tools/` | 21 agent tools | Yes |
+| `agent/backtest/` | Backtest engines, loaders, optimizers | Yes |
+| `agent/config/swarm/` | 29 swarm preset YAMLs | Yes |
+| `frontend/` | React 19 + Vite web UI | Yes |
+| `agent/src/agent/` | ReAct agent core (loop, context, skills) | Ask first |
+| `agent/src/session/` | Session management | Ask first |
+| `agent/src/providers/` | LLM provider abstraction | Ask first |
+
+> **Core modules** (`agent/`, `session/`, `providers/`) are protected — please open an issue to discuss before modifying.
+
+## How to Contribute
+
+### Reporting Bugs
+
+Use the [Bug Report](https://github.com/HKUDS/Vibe-Trading/issues/new?template=bug_report.yml) template. Include:
+
+- Steps to reproduce
+- Expected vs actual behavior
+- Your environment (OS, Python version, provider)
+- Error logs if available
+
+### Suggesting Features
+
+Use the [Feature Request](https://github.com/HKUDS/Vibe-Trading/issues/new?template=feature_request.yml) template.
+
+### Submitting Code
+
+1. **Fork & branch** — create a feature branch from `main`
+   ```bash
+   git checkout -b feat/my-feature
+   ```
+
+2. **Make changes** — follow the code standards below
+
+3. **Test** — add or update tests, ensure `pytest` passes
+   ```bash
+   pytest --ignore=agent/tests/e2e_backtest --tb=short -q
+   ```
+
+4. **Commit** — use [Conventional Commits](https://www.conventionalcommits.org/)
+   ```
+   feat: add RSI divergence skill
+   fix: handle empty DataFrame in backtest loader
+   docs: update CLI reference table
+   test: add crypto engine edge cases
+   ```
+
+5. **Pull Request** — open a PR against `main` with:
+   - Summary of changes
+   - Related issue number (e.g., `Closes #42`)
+   - Test plan
+
+## Code Standards
+
+- **Python**: Google-style docstrings, type hints encouraged
+- **No hardcoding**: config via `.env`, YAML, or constants
+- **Delete unused code** — don't comment-preserve
+- **OKX pairs**: use `BTC-USDT` format (hyphen, uppercase)
+- **UI text**: English. LLM output follows user language
+- **File size**: aim for < 400 lines, max 800
+
+## Contribution Roadmap
+
+### Easy: New Skill
+
+Each skill is a single `SKILL.md` file in `agent/src/skills/<category>/<skill-name>/`. Categories: `data-source`, `strategy`, `analysis`, `asset-class`, `crypto`, `flow`, `tool`. Look at existing skills for the format.
+
+### Easy: New Swarm Preset
+
+A YAML file in `agent/config/swarm/` defining agents, roles, and DAG workflow. See existing presets.
+
+### Medium: New Data Source Loader
+
+1. Create `agent/backtest/loaders/<source>.py`
+2. Implement the `DataLoader` Protocol (see `agent/backtest/loaders/base.py`)
+3. Register in `agent/backtest/loaders/registry.py`
+4. Add tests in `agent/tests/`
+
+### Medium: Portfolio Optimizer Constraints
+
+Current optimizers (`agent/backtest/optimizers/`) support basic weight optimization. We need:
+- **Leverage constraints** — max gross exposure limits
+- **Sector/group caps** — weight limits per sector or asset group
+- **Turnover penalties** — transaction cost-aware rebalancing
+- Extend `BaseOptimizer` interface, keep backward compatibility
+
+### Medium: Correlation Heatmap Dashboard
+
+Add a cross-asset correlation matrix component to the frontend:
+- Time-window slider (30d / 60d / 90d / 1Y)
+- Hierarchical clustering for sector grouping
+- ECharts heatmap or custom canvas renderer
+- Wire to a new API endpoint that computes rolling correlations
+
+### Hard: Intraday Backtest Engine
+
+Current engines run on daily bars. We need sub-daily execution:
+- Support 1m / 5m / 15m / 30m / 1H / 4H intervals
+- Handle market session boundaries (pre-market, after-hours, overnight gaps)
+- Intraday margin / buying power tracking
+- Integrate with minute-level data loaders (OKX klines, yfinance intraday)
+- Start from `BaseEngine` — see `agent/backtest/engines/base.py` for the abstract interface
+
+### Hard: Options Volatility Surface & Greeks Visualization
+
+Build 3D implied-vol surface and Greeks charts in the frontend:
+- **Vol surface**: strike vs. expiry vs. implied vol (3D mesh or contour)
+- **Greeks dashboard**: delta, gamma, theta, vega curves across strikes
+- **Skew chart**: 25-delta risk reversal over time
+- Backend: extend `options_pricing_tool.py` to return surface data
+- Frontend: ECharts GL for 3D, or custom WebGL renderer
+
+### Hard: Monte Carlo & Stress Testing
+
+Add scenario simulation and tail-risk analysis:
+- **Monte Carlo**: generate N return paths from fitted distribution, compute VaR/CVaR confidence intervals
+- **Historical stress tests**: replay specific crisis periods (2008, 2020 COVID, 2022 crypto winter)
+- **Regime switching**: HMM-based regime detection (bull/bear/sideways), conditional risk metrics
+- Output: distribution plots, drawdown probability curves, worst-case tables
+- Can be a new tool in `agent/src/tools/` or an extension to the backtest engine
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).
@@ -33,7 +33,8 @@
  <a href="#-cli-reference">CLI</a> &nbsp;&middot;&nbsp;
  <a href="#-api-server">API</a> &nbsp;&middot;&nbsp;
  <a href="#-mcp-plugin">MCP</a> &nbsp;&middot;&nbsp;
-  <a href="#-project-structure">Structure</a>
+  <a href="#-project-structure">Structure</a> &nbsp;&middot;&nbsp;
+  <a href="#-contributing">Contributing</a>
 </p>

 <p align="center">
@@ -568,6 +569,27 @@ Vibe-Trading is part of the **[HKUDS](https://github.com/HKUDS)** agent ecosyste

 ---

+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+**Good first issues** are tagged with [`good first issue`](https://github.com/HKUDS/Vibe-Trading/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — great for getting started.
+
+Areas we'd love help with:
+
+| Area | Difficulty | Description |
+|------|:----------:|-------------|
+| Intraday backtest engine | Hard | Sub-daily (1m/5m/1H) bar execution with proper session handling |
+| Options vol surface & Greeks viz | Hard | 3D implied-vol surface, delta/gamma/vega charts in frontend |
+| Monte Carlo & stress testing | Hard | Scenario simulation, regime-switching, tail-risk analysis |
+| Portfolio optimizer constraints | Medium | Leverage limits, sector caps, turnover penalties |
+| Correlation heatmap dashboard | Medium | Cross-asset correlation matrix with time-window slider |
+| New data source loader | Medium | Implement `DataLoader` Protocol for a new exchange/vendor |
+| New finance skill | Easy | Add a `SKILL.md` — e.g., pairs trading, mean reversion, VWAP |
+| New swarm preset | Easy | YAML config for a new multi-agent workflow |
+
+---
+
 ## Disclaimer

 Vibe-Trading is for research, simulation, and backtesting only. It is not investment advice and it does not execute live trades. Past performance does not guarantee future results.