Guía de contribución

DispatchAtlas acepta cambios que preserven los límites de paquete, la evidencia determinista, y las afirmaciones públicas con gate de lanzamiento. Las contribuciones se escriben a partir de los contratos del repositorio — no se copian de árboles de fuente externos, informes generados, o artefactos de experimento no publicados. El CONTRIBUTING.md raíz es la lista de verificación autoritativa; esta página lo mapea sobre la base de código.

🧭 Elige tu camino

Las reglas de límites de cada carpeta viven en el AGENTS.md raíz; cada carpeta de paquete también lleva su propio README.md.

Intención	Camino	Dónde
Arreglar un bug de solver	Registro de solvers, operadores, o metaheurísticas, más pruebas de comportamiento.	`packages/dispatchatlas-solve/` (ver su README) y `tests/solve/`.
Añadir una familia de benchmarks	Generador, entrada de taxonomía, fila de matriz de citación, cableado de catálogo.	`packages/dispatchatlas-bench/` (ver su README) y `tests/bench/`.
Extender contratos de dominio	Modelo de planificación, validación, procedencia, o serialización en el límite interno.	`packages/dispatchatlas-core/` (ver su README) y `tests/core/`.
Mejorar la ejecución de campañas	Configuración, presupuestos, puntos de control, reintentos, captura de entorno.	`packages/dispatchatlas-lab/` (ver su README) y `tests/lab/`.
Extender exportaciones de análisis	Estadísticas, filtrado de divulgación, paquetes de evidencia, conjuntos de datos del portal, CLI.	`packages/dispatchatlas-analytica/` (ver su README) y `tests/analytica/`.
Mejorar la documentación	Páginas del sitio sobre el stack de documentación Next.js.	`site/content/docs/` (ver `site/README.md`).
Añadir un ejemplo ejecutable	Ejemplos a escala de prueba, configurables, seguros-para-el-público.	`examples/` (su README lista las cubetas de ejemplo y las reglas).
Mejorar el tooling de calidad	Gates de build, prose-register, code-first, y license-header.	`tools/` (ver su README) y `tests/tools/`.
Reportar un bug o hacer una pregunta	Formularios de issues estructurados y los canales de soporte.	Formularios de issues y `SUPPORT.md`.

⚙️ Configuración local

Instala Python 3.12 o más nuevo.
Instala uv.
Ejecuta uv sync --all-extras --group dev.
Ejecuta uv run pre-commit install si quieres hooks de commit locales.

✅ Comprobaciones locales

Ejecuta estas antes de abrir un pull request — la CI alojada corre el mismo conjunto de gates a través de la matriz de OS y 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

Para comprobaciones de prueba de build de paquetes:

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"

📦 Límites

Mantén los imports dentro de la dirección de dependencia documentada — ver la descripción general de arquitectura para el diagrama y la tabla de imports por paquete. La forma corta:

dispatchatlas.core es el límite de dominio interno e importa ningún paquete DispatchAtlas.
dispatchatlas.bench y dispatchatlas.solve dependen solo de core.
dispatchatlas.lab compone los paquetes core, benchmark, y solver.
dispatchatlas.analytica consume los contratos de core y manifiestos estables.
site/ consume exportaciones aprobadas; tools/ y CI inspeccionan cada paquete pero no son dependencias de runtime del producto.

El límite es impuesto por tests/architecture/test_import_boundaries.py, de modo que un import que cruce falla la suite de pruebas antes de la revisión.

📋 Expectativas de pull request

Área	Expectativa
Código	Mantén los imports dentro de la dirección de dependencia documentada.
Datos	Trata las salidas de campaña como evidencia generada, no archivos de fuente.
Docs	Usa lenguaje DispatchAtlas de primer-lanzamiento, mantén la evidencia de prueba etiquetada, y actualiza las páginas cuando el comportamiento de cara-al-usuario cambie.
Pruebas	Añade aserciones de comportamiento para nuevos contratos públicos; describe el comportamiento esperado en lugar de reproducir estructura externa.
Seguridad	No comprometas credenciales, evidencia privada, o secretos de despliegue.
Artefactos generados	Mantén cachés, salidas de build, informes de cobertura, salidas de experimento, y puntos de control fuera de Git a menos que una política del repositorio los nombre como fuente rastreada.

🤝 Comunidad y soporte

Los canales de comunidad, formularios de issues, y categorías de discusión están resumidos en la página de comunidad. El ciclo de vida de contribución — proponer, alinear, implementar, revisar, fusionar — está registrado en GOVERNANCE.md.