Contribution Guide

How to contribute to DispatchAtlas — package boundaries, deterministic behavior, the local quality gate, and the conventions every change must preserve.

DispatchAtlas accepts changes that preserve package boundaries, deterministic evidence, and release-gated public claims. Contributions are written from the repository contracts — not copied from outside source trees, generated reports, or unpublished experiment artifacts. The root CONTRIBUTING.md is the authoritative checklist; this page maps it onto the codebase.

🧭 Choose Your Path

Boundary rules for every folder live in the root AGENTS.md; each package folder also carries its own README.md.

Intent	Path	Where
Fix a solver bug	Solver registry, operators, or metaheuristics, plus behavior tests.	`packages/dispatchatlas-solve/` (see its README) and `tests/solve/`.
Add a benchmark family	Generator, taxonomy entry, citation matrix row, catalog wiring.	`packages/dispatchatlas-bench/` (see its README) and `tests/bench/`.
Extend domain contracts	Scheduling model, validation, provenance, or serialization in the inner boundary.	`packages/dispatchatlas-core/` (see its README) and `tests/core/`.
Improve campaign execution	Configuration, budgets, checkpoints, retries, environment capture.	`packages/dispatchatlas-lab/` (see its README) and `tests/lab/`.
Extend analysis exports	Statistics, disclosure filtering, evidence bundles, portal datasets, CLI.	`packages/dispatchatlas-analytica/` (see its README) and `tests/analytica/`.
Improve the documentation	Site pages on the Next.js documentation stack.	`site/content/docs/` (see `site/README.md`).
Add a runnable example	Smoke-scale, configurable, public-safe examples.	`examples/` (its README lists the example buckets and rules).
Improve quality tooling	Build, prose-register, code-first, and license-header gates.	`tools/` (see its README) and `tests/tools/`.
Report a bug or ask a question	Structured issue forms and the support channels.	Issue forms and `SUPPORT.md`.

⚙️ Local Setup

Install Python 3.12 or newer.
Install uv.
Run uv sync --all-extras --group dev.
Run uv run pre-commit install if you want local commit hooks.

✅ Local Checks

Run these before opening a pull request — hosted CI runs the same gate set across the OS and Python matrix:

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

For package-build smoke checks:

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"

📦 Boundaries

Keep imports inside the documented dependency direction — see the architecture overview for the diagram and the per-package import table. The short form:

dispatchatlas.core is the inner domain boundary and imports no DispatchAtlas package.
dispatchatlas.bench and dispatchatlas.solve depend on core only.
dispatchatlas.lab composes core, benchmark, and solver packages.
dispatchatlas.analytica consumes core contracts and stable manifests.
site/ consumes approved exports; tools/ and CI inspect every package but are not product runtime dependencies.

The boundary is enforced by tests/architecture/test_import_boundaries.py, so a crossing import fails the test suite before review.

📋 Pull Request Expectations

Area	Expectation
Code	Keep imports inside the documented dependency direction.
Data	Treat campaign outputs as generated evidence, not source files.
Docs	Use first-release DispatchAtlas language, keep smoke evidence labeled, and update pages when user-facing behavior changes.
Tests	Add behavioral assertions for new public contracts; describe expected behavior rather than reproducing external structure.
Security	Do not commit credentials, private evidence, or deployment secrets.
Generated artifacts	Keep caches, build outputs, coverage reports, experiment outputs, and checkpoints out of Git unless a repository policy names them as tracked source.

🤝 Community And Support

Community channels, issue forms, and discussion categories are summarized on the community page. The contribution lifecycle — propose, align, implement, review, merge — is recorded in GOVERNANCE.md.