pf1e-simulator/docs/contributing.md

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

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)

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
4. 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

# 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.