# Contributing to LLMHosts.com

## Getting Started

### Prerequisites
- Python 3.12+
- Node.js 22+
- Docker (for containerized dev)

### Setup

```bash
# Clone
git clone https://github.com/LookNoHandsMom/LLMHosts.com.git
cd LLMHosts.com

# Install (editable with dev deps)
pip install -e ".[dev]"

# Verify
pytest tests/ -v
llmhosts doctor
```

## Development Workflow

### Branching

- `main` — production-ready, squash-merged PRs only
- `develop` — integration branch
- `feature/<id>-<desc>` — feature branches
- `fix/<id>-<desc>` — bug fix branches

### Commits

We use [Conventional Commits](https://www.conventionalcommits.org/):

```
feat(scope): add new feature
fix(scope): fix a bug
docs: update documentation
refactor: restructure code
test: add or fix tests
chore: CI, deps, tooling
```

### Pull Requests

1. Branch from `main`
2. Write tests first (TDD)
3. Implement the feature
4. Run the full check suite:
   ```bash
   ruff check .
   ruff format --check .
   mypy llmhost/ --ignore-missing-imports
   pytest tests/ -v
   ```
5. Open PR against `main`
6. Fill out the PR template completely

**Self-Healing CI**: Our CI pipeline automatically fixes lint/format issues and commits them back to your PR. If you see a commit from `github-actions[bot]` with `[skip ci]`, pull the latest changes before continuing work.

### CI Pipeline (T-13, P-005 Compliant)

Our CI pipeline implements **zero-tolerance** (zero warnings, zero errors, zero failing tests) with **self-healing** capabilities:

#### Phase 1: Parallel Checks

**Python Jobs:**
- `python-typecheck`: MyPy type checking
- `python-lint`: Ruff check + format (self-healing)
- `python-test`: pytest with coverage
- `python-security`: Bandit security scan

**Frontend Jobs:**
- `frontend-typecheck`: TypeScript strict checking
- `frontend-lint`: ESLint (self-healing)
- `frontend-test`: Vitest with coverage
- `frontend-build`: Next.js build (zero-warning policy)
- `frontend-security`: npm audit for vulnerabilities

**Infrastructure:**
- `docker-build`: Verify both dev and production images build
- `secret-scan`: GitLeaks for exposed secrets

#### Phase 2: Verification Gate

The `verify-all` job ensures **ALL** Phase 1 jobs passed before allowing merge. This is a hard gate - if any check fails, the PR cannot be merged.

#### Self-Healing Behavior

When lint or format checks fail, the CI will:
1. Run auto-fix (`ruff check --fix`, `ruff format`, or `eslint --fix`)
2. Re-check to verify fixes worked
3. **If fixes succeed**: Commit changes with `[skip ci]` and continue
4. **If fixes fail**: Mark job as failed and require human intervention

**When to pull latest changes:**
- After seeing a `github-actions[bot]` commit in your PR
- Before pushing new commits to avoid conflicts

#### Skipping CI

Use `[skip ci]` in commit messages **only** when:
- The change is documentation-only
- You're making a trivial fix to a previous commit
- CI already passed and you're making a non-code change

**Never** skip CI for code changes.

#### Git Hooks (Optional but Recommended)

We provide Husky git hooks that run the same checks locally:
- `pre-commit`: Auto-fixes Python and frontend files before commit
- `commit-msg`: Validates conventional commit format

The hooks are automatically installed when you run `npm install` in the `frontend/` directory.

### Code Standards

- **Python**: ruff for lint+format, mypy for types, line-length 120
- **TypeScript**: strict mode, ESLint + Prettier
- **All**: async/await everywhere, Pydantic v2 for validation
- **Tests**: pytest with ASGI transport, no real server needed

### Architecture

Before making changes, review:
- `docs/architecture/` — ADRs and system design
- `CLAUDE.md` — project conventions and patterns
- `.cursor/rules/` — coding standards

## Issue Labels

| Label | Meaning |
|-------|---------|
| `type:feature` | New capability |
| `type:bug` | Something broken |
| `type:chore` | CI, deps, refactor |
| `priority:critical` | Service down |
| `priority:high` | Major feature broken |
| `size:xs` to `size:xl` | Effort estimate |

## Questions?

Open an issue with the `type:chore` template or check `docs/` for existing documentation.
