# Guidelines de contribution

Merci de votre intérêt pour contribuer à pf1e-simulator !

## Standards de code

### Langage & outils
- **Python ≥ 3.12** — typage strict, pas de `Any`, pas de `# type: ignore`
- **uv** pour la gestion de l'environnement (`uv sync --dev`)
- **Ruff** : `select = ["ALL"]`, longueur de ligne 100
- **Basedpyright** : mode strict sur `src` et `tests`
- **Pytest** : tests déterministes, transcripts épinglés

### Conventions Python
- **Dataclasses frozen** par défaut (`@dataclass(frozen=True)`)
- **Types explicites** — pas d'inférence ambiguë
- **Docstrings** sur les API publiques (modules, classes, fonctions publiques)
- **EM101/EM102** : messages d'erreur explicites (`msg = ...; raise X(msg)`)
- **Pas de `type: ignore` / `cast()` / `Any`** — le typage strict est la norme

### Architecture
- **Modules petits** (< 250 lignes) — séparation des responsabilités
- **Pas de cycles d'import** — dépendances unidirectionnelles
- **Interfaces explicites** — `Protocol` ou classes abstraites pour l'injection
- **Tests purs** — pas de réseau, pas d'état global, `FakeLLMClient` pour LLM

---

## Processus de développement

### 1. Branche & commits
```bash
git checkout -b feat/ma-fonctionnalité
# Travail...
git add -A
git commit -m "feat(scope): description courte

Description plus longue si nécessaire, wrapping à 72 caractères.

Refs: #issue-number"
```

**Style de commit** : Conventional Commits
- `feat(scope): ...` — nouvelle fonctionnalité
- `fix(scope): ...` — correction de bug
- `docs(scope): ...` — documentation
- `refactor(scope): ...` — refactoring sans changement fonctionnel
- `test(scope): ...` — ajout/modification de tests
- `chore: ...` — maintenance (deps, config, etc.)

### 2. Gate de validation (obligatoire avant PR)
```bash
uv run pytest -q
uv run ruff check src tests
uv run basedpyright src
```
**Tous doivent passer** — pas d'exceptions.

### 3. Tests
- **Couverture** : nouvelles fonctionnalités = nouveaux tests
- **Determinisme** : `ScriptedRng` / `FakeLLMClient` pour tests LLM
- **Transcripts épinglés** : combats 1v1/2v2 scriptés
- **Assertions statistiques** : forme fermée (bande 3σ sur matchup symétrique)
- **Noms de tests** : `test_<fonctionnalité>_<scénario>_<résultat_attendu>`

### 4. Documentation
- **API publiques** : docstrings complètes
- **Architecture** : mises à jour dans `docs/architecture/`
- **Règles** : conformité SRD dans `docs/rules/conformance-srd.md`
- **Formats** : exemples dans `docs/data-formats/`

---

## Types de contributions

### Bug fixes
1. Ouvrir une issue (template bug) avec reproduction minimale
2. Écrire un test qui échoue (reproduction)
3. Corriger le code
3. Vérifier gate complète

### Nouvelles fonctionnalités
1. Ouvrir une issue (template feature) avec design/discussion
2. Découper en tranches atomiques testables (cf. `docs/architecture/phase-2-llm-architecture.md`)
3. Implémenter tranche par tranche, gate à chaque étape
4. Doc + tests + architecture doc mise à jour

### Refactoring
- Gate complète avant et après
- Pas de changement fonctionnel
- Commits `refactor(scope): ...`

### Documentation
- Corrections typo/clarification : commits `docs: ...`
- Nouvelles sections : suivi structure `docs/`

---

## Configuration locale recommandée

```bash
# Pre-commit (optionnel mais recommandé)
uv pip install pre-commit
pre-commit install

# Éditeur : config basedpyright + ruff
# VS Code : extensions Python, Ruff, Basedpyright
```

---

## Code review

### Ce qu'on regarde
- ✅ Gate complète passe
- ✅ Tests pertinents + passants
- ✅ Typage strict (pas de `Any`, `ignore`, `cast`)
- ✅ Architecture respectée (modules, dépendances)
- ✅ Docstrings sur API publiques
- ✅ Messages d'erreur explicites (EM101/EM102)
- ✅ Pas de code mort / code commenté
- ✅ Commits atomiques, messages clairs

### Red flags (rejettent la PR)
- ❌ Gate qui ne passe pas
- ❌ `type: ignore` / `# type: ignore` / `cast()`
- ❌ Tests supprimés sans remplacement
- ❌ Code non testé (nouvelle logique sans test)
- ❌ Dépendances circulaires
- ❌ Code mort / `pass` / `TODO` sans issue

---

## Signalement de sécurité

Pour les vulnérabilités potentielles : **ne pas ouvrir d'issue publique**.
Envoyer un email à l'équipe de maintenance (voir `SECURITY.md` ou `AUTHORS`).

---

## Licence

En contribuant, vous acceptez que votre contribution soit sous la même licence que le projet (voir `LICENSE`).

---

## Questions ?

Ouvrez une discussion GitHub ou consultez `docs/architecture/` pour l'architecture technique.