ctan
f61fc5c61f
- Clean README.md with installation, usage, CLI, examples - Move data formats to docs/data-formats/ (map.md, monster.md, pc-sheets.md, index.md) - Move architecture to docs/architecture/ (index.md, technical-architecture.md, phase-2-llm-architecture.md) - Add contributing guidelines in docs/contributing.md - Clean README.md: install, usage, CLI, data-formats/rules/architecture links, contributing link
149 lines
4.5 KiB
Markdown
149 lines
4.5 KiB
Markdown
# 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. |