Guia de contribuição

O DispatchAtlas aceita mudanças que preservem os limites de pacote, a evidência determinística, e as afirmações públicas com gate de lançamento. As contribuições são escritas a partir dos contratos do repositório — não copiadas de árvores de fonte externas, relatórios gerados, ou artefatos de experimento não publicados. O CONTRIBUTING.md raiz é a lista de verificação autoritativa; esta página o mapeia sobre a base de código.

🧭 Escolha seu caminho

As regras de limites de cada pasta vivem no AGENTS.md raiz; cada pasta de pacote também carrega seu próprio README.md.

Intenção	Caminho	Onde
Corrigir um bug de solver	Registro de solvers, operadores, ou metaheurísticas, mais testes de comportamento.	`packages/dispatchatlas-solve/` (ver seu README) e `tests/solve/`.
Adicionar uma família de benchmarks	Gerador, entrada de taxonomia, linha de matriz de citação, cabeamento de catálogo.	`packages/dispatchatlas-bench/` (ver seu README) e `tests/bench/`.
Estender contratos de domínio	Modelo de escalonamento, validação, proveniência, ou serialização no limite interno.	`packages/dispatchatlas-core/` (ver seu README) e `tests/core/`.
Melhorar a execução de campanhas	Configuração, orçamentos, pontos de verificação, retentativas, captura de ambiente.	`packages/dispatchatlas-lab/` (ver seu README) e `tests/lab/`.
Estender exportações de análise	Estatísticas, filtragem de divulgação, pacotes de evidência, conjuntos de dados do portal, CLI.	`packages/dispatchatlas-analytica/` (ver seu README) e `tests/analytica/`.
Melhorar a documentação	Páginas do site sobre o stack de documentação Next.js.	`site/content/docs/` (ver `site/README.md`).
Adicionar um exemplo executável	Exemplos em escala de fumaça, configuráveis, seguros-para-o-público.	`examples/` (seu README lista os baldes de exemplo e as regras).
Melhorar o tooling de qualidade	Gates de build, prose-register, code-first, e license-header.	`tools/` (ver seu README) e `tests/tools/`.
Reportar um bug ou fazer uma pergunta	Formulários de issues estruturados e os canais de suporte.	Formulários de issues e `SUPPORT.md`.

⚙️ Configuração local

Instale Python 3.12 ou mais novo.
Instale uv.
Execute uv sync --all-extras --group dev.
Execute uv run pre-commit install se você quiser hooks de commit locais.

✅ Verificações locais

Execute estas antes de abrir um pull request — a CI hospedada roda o mesmo conjunto de gates através da matriz de OS e 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 verificações de fumaça de build de pacotes:

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

Mantenha os imports dentro da direção de dependência documentada — ver a visão geral de arquitetura para o diagrama e a tabela de imports por pacote. A forma curta:

dispatchatlas.core é o limite de domínio interno e importa nenhum pacote DispatchAtlas.
dispatchatlas.bench e dispatchatlas.solve dependem apenas de core.
dispatchatlas.lab compõe os pacotes core, benchmark, e solver.
dispatchatlas.analytica consome os contratos de core e manifestos estáveis.
site/ consome exportações aprovadas; tools/ e CI inspecionam cada pacote mas não são dependências de runtime do produto.

O limite é imposto por tests/architecture/test_import_boundaries.py, de modo que um import que cruza falha a suíte de testes antes da revisão.

📋 Expectativas de pull request

Área	Expectativa
Código	Mantenha os imports dentro da direção de dependência documentada.
Dados	Trate as saídas de campanha como evidência gerada, não arquivos de fonte.
Docs	Use linguagem DispatchAtlas de primeiro-lançamento, mantenha a evidência de fumaça rotulada, e atualize as páginas quando o comportamento de cara-ao-usuário mudar.
Testes	Adicione asserções de comportamento para novos contratos públicos; descreva o comportamento esperado em vez de reproduzir estrutura externa.
Segurança	Não comprometa credenciais, evidência privada, ou segredos de implantação.
Artefatos gerados	Mantenha caches, saídas de build, relatórios de cobertura, saídas de experimento, e pontos de verificação fora do Git a menos que uma política do repositório os nomeie como fonte rastreada.

🤝 Comunidade e suporte

Os canais de comunidade, formulários de issues, e categorias de discussão estão resumidos na página de comunidade. O ciclo de vida de contribuição — propor, alinhar, implementar, revisar, mesclar — está registrado em GOVERNANCE.md.