docs: reorganize documentation structure
- 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
This commit is contained in:
@@ -0,0 +1,149 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user