Guide de contribution

DispatchAtlas accepte les changements qui préservent les limites de paquet, la preuve déterministe, et les affirmations publiques à gate de publication. Les contributions sont écrites à partir des contrats du dépôt — non copiées d'arbres de source externes, de rapports générés, ou d'artefacts d'expérience non publiés. Le CONTRIBUTING.md racine est la liste de vérification autoritative ; cette page le cartographie sur la base de code.

🧭 Choisissez votre voie

Les règles de limites de chaque dossier vivent dans le AGENTS.md racine ; chaque dossier de paquet porte aussi son propre README.md.

Intention	Voie	Où
Corriger un bug de solveur	Registre de solveurs, opérateurs, ou métaheuristiques, plus tests de comportement.	`packages/dispatchatlas-solve/` (voir son README) et `tests/solve/`.
Ajouter une famille de benchmarks	Générateur, entrée de taxonomie, ligne de matrice de citation, câblage de catalogue.	`packages/dispatchatlas-bench/` (voir son README) et `tests/bench/`.
Étendre les contrats de domaine	Modèle de planification, validation, provenance, ou sérialisation dans la limite interne.	`packages/dispatchatlas-core/` (voir son README) et `tests/core/`.
Améliorer l'exécution de campagnes	Configuration, budgets, points de contrôle, réessais, capture d'environnement.	`packages/dispatchatlas-lab/` (voir son README) et `tests/lab/`.
Étendre les exports d'analyse	Statistiques, filtrage de divulgation, lots de preuves, jeux de données du portail, CLI.	`packages/dispatchatlas-analytica/` (voir son README) et `tests/analytica/`.
Améliorer la documentation	Pages du site sur le stack de documentation Next.js.	`site/content/docs/` (voir `site/README.md`).
Ajouter un exemple exécutable	Exemples à l'échelle de test, configurables, sûrs-pour-le-public.	`examples/` (son README liste les seaux d'exemple et les règles).
Améliorer l'outillage de qualité	Gates de build, prose-register, code-first, et license-header.	`tools/` (voir son README) et `tests/tools/`.
Signaler un bug ou poser une question	Formulaires d'issues structurés et les canaux de support.	Formulaires d'issues et `SUPPORT.md`.

⚙️ Configuration locale

Installez Python 3.12 ou plus récent.
Installez uv.
Exécutez uv sync --all-extras --group dev.
Exécutez uv run pre-commit install si vous voulez des hooks de commit locaux.

✅ Vérifications locales

Exécutez celles-ci avant d'ouvrir une pull request — la CI hébergée exécute le même ensemble de gates à travers la matrice d'OS et de Python :

uv run ruff format --check .
uv run ruff check .
uv run mypy packages tests tools examples
uv run coverage run -m pytest
uv run coverage report
uv run python tools/check_prose_register.py
uv run python tools/check_code_first.py
uv run python tools/check_root_outputs.py
uv run python tools/check_solver_metaphors.py
uv run python tools/license_header.py check
uv run reuse lint
gitleaks detect --source . --redact --config .gitleaks.toml
npm --prefix site run build
npm --prefix site run check
npm --prefix site audit --audit-level=moderate
uv run pip-audit --path .\.venv\Lib\site-packages --progress-spinner off

Pour les vérifications de test de build de paquets :

uv run python tools/build_packages.py
uv venv .package-smoke
uv pip install --python .\.package-smoke\Scripts\python.exe (Get-ChildItem .\packages\*\dist\*.whl)
.\.package-smoke\Scripts\python.exe -c "import dispatchatlas, dispatchatlas.core, dispatchatlas.bench, dispatchatlas.solve, dispatchatlas.lab, dispatchatlas.analytica"

📦 Limites

Gardez les imports dans la direction de dépendance documentée — voir la description générale de l'architecture pour le diagramme et la table d'imports par paquet. La forme courte :

dispatchatlas.core est la limite de domaine interne et n'importe aucun paquet DispatchAtlas.
dispatchatlas.bench et dispatchatlas.solve ne dépendent que de core.
dispatchatlas.lab compose les paquets core, benchmark, et solver.
dispatchatlas.analytica consomme les contrats de core et les manifestes stables.
site/ consomme les exports approuvés ; tools/ et CI inspectent chaque paquet mais ne sont pas des dépendances de runtime du produit.

La limite est imposée par tests/architecture/test_import_boundaries.py, de sorte qu'un import qui traverse échoue la suite de tests avant la revue.

📋 Attentes de pull request

Domaine	Attente
Code	Gardez les imports dans la direction de dépendance documentée.
Données	Traitez les sorties de campagne comme une preuve générée, non des fichiers de source.
Docs	Utilisez un langage DispatchAtlas de première-publication, gardez la preuve de test étiquetée, et mettez à jour les pages quand le comportement face-à-l'utilisateur change.
Tests	Ajoutez des assertions de comportement pour les nouveaux contrats publics ; décrivez le comportement attendu plutôt que de reproduire la structure externe.
Sécurité	Ne committez pas d'identifiants, de preuve privée, ou de secrets de déploiement.
Artefacts générés	Gardez les caches, sorties de build, rapports de couverture, sorties d'expérience, et points de contrôle hors de Git à moins qu'une politique du dépôt ne les nomme comme source suivie.

🤝 Communauté et support

Les canaux communautaires, formulaires d'issues, et catégories de discussion sont résumés sur la page communauté. Le cycle de vie de contribution — proposer, aligner, implémenter, réviser, fusionner — est consigné dans GOVERNANCE.md.