# Contributing to Nexus

Thank you for your interest in contributing! 🎉

## Quick Start

```bash
# Clone the repo
git clone https://github.com/songtianye/nexus.git
cd nexus

# Create environment (requires uv — https://docs.astral.sh/uv/)
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -e ".[all,dev]"

# Verify
.venv/bin/python tests/test_smoke.py
.venv/bin/ruff check nexus/
```

## How to Contribute

### Report Bugs

- Use [GitHub Issues](https://github.com/songtianye/nexus/issues)
- Include: Python version, OS, minimal reproduction code, full error traceback

### Suggest Features

- Open a [Discussion](https://github.com/songtianye/nexus/discussions) first
- Describe the **use case**, not just the solution

### Submit Code

1. **Fork** the repository
2. **Create a branch**: `git checkout -b feature/amazing-feature`
3. **Write code** following the style guide below
4. **Add tests** for new functionality
5. **Run checks**: `ruff check nexus/ && python tests/test_smoke.py`
6. **Commit**: use [Conventional Commits](https://www.conventionalcommits.org/) format
7. **Push & open a Pull Request**

## Code Style

| Rule | Tool |
|------|------|
| Formatter / Linter | [Ruff](https://docs.astral.sh/ruff/) |
| Type hints | Required for all public APIs |
| Docstrings | Google style |
| Line length | 100 characters |
| Python | 3.11+, use modern features (`X \| Y` unions, `match`, etc.) |

```bash
ruff format nexus/     # Format
ruff check nexus/ --fix # Lint + auto-fix
```

## Where to Contribute

| Area | Difficulty | Path |
|------|-----------|------|
| Bug fixes | 🟢 Easy | Anywhere |
| Documentation | 🟢 Easy | `README.md`, `examples/` |
| New tools / examples | 🟡 Medium | `examples/` |
| New model provider | 🟡 Medium | `nexus/models/` |
| Orchestration | 🔴 Hard | `nexus/orchestration/` |
| Protocol extensions | 🔴 Hard | `nexus/protocol/` |

## Commit Convention

```
feat: add streaming response support
fix: resolve checkpoint restore race condition
docs: update MCP integration examples
refactor: simplify router scoring logic
test: add adaptive orchestrator unit tests
chore: update dependencies
```

## Code of Conduct

Be kind, be respectful, be constructive. We're all here to build something great.

---

Questions? Open an [issue](https://github.com/songtianye/nexus/issues) or start a [discussion](https://github.com/songtianye/nexus/discussions).
