Beitragsleitfaden

DispatchAtlas akzeptiert Änderungen, die Paketgrenzen, deterministische Belege, und release-gesperrte öffentliche Aussagen bewahren. Beiträge werden aus den Repository-Verträgen geschrieben — nicht aus externen Quellbäumen, generierten Berichten, oder unveröffentlichten Experiment-Artefakten kopiert. Das Wurzel- CONTRIBUTING.md ist die autoritative Checkliste; diese Seite bildet sie auf die Codebasis ab.

🧭 Wähle deinen Pfad

Die Grenzregeln jedes Ordners leben im Wurzel- AGENTS.md; jeder Paketordner trägt zudem sein eigenes README.md.

Absicht	Pfad	Wo
Einen Solver-Bug beheben	Solver-Registry, Operatoren, oder Metaheuristiken, plus Verhaltenstests.	`packages/dispatchatlas-solve/` (siehe sein README) und `tests/solve/`.
Eine Benchmark-Familie hinzufügen	Generator, Taxonomie-Eintrag, Zitationsmatrix-Zeile, Katalog-Verdrahtung.	`packages/dispatchatlas-bench/` (siehe sein README) und `tests/bench/`.
Domänenverträge erweitern	Planungsmodell, Validierung, Provenienz, oder Serialisierung in der inneren Grenze.	`packages/dispatchatlas-core/` (siehe sein README) und `tests/core/`.
Kampagnenausführung verbessern	Konfiguration, Budgets, Prüfpunkte, Wiederholungen, Umgebungserfassung.	`packages/dispatchatlas-lab/` (siehe sein README) und `tests/lab/`.
Analyse-Exporte erweitern	Statistik, Offenlegungsfilterung, Belegpakete, Portal-Datensätze, CLI.	`packages/dispatchatlas-analytica/` (siehe sein README) und `tests/analytica/`.
Die Dokumentation verbessern	Site-Seiten auf dem Next.js-Dokumentations-Stack.	`site/content/docs/` (siehe `site/README.md`).
Ein ausführbares Beispiel hinzufügen	Smoke-skalierte, konfigurierbare, öffentlich-sichere Beispiele.	`examples/` (sein README listet die Beispiel-Eimer und Regeln).
Quality-Tooling verbessern	Build-, prose-register-, code-first-, und license-header-Gates.	`tools/` (siehe sein README) und `tests/tools/`.
Einen Bug melden oder eine Frage stellen	Strukturierte Issue-Formulare und die Support-Kanäle.	Issue-Formulare und `SUPPORT.md`.

⚙️ Lokale Einrichtung

Installiere Python 3.12 oder neuer.
Installiere uv.
Führe uv sync --all-extras --group dev aus.
Führe uv run pre-commit install aus, wenn du lokale Commit-Hooks möchtest.

✅ Lokale Prüfungen

Führe diese aus, bevor du eine Pull Request eröffnest — das gehostete CI führt denselben Gate-Satz über die OS- und Python-Matrix aus:

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

Für Paket-Build-Smoke-Prüfungen:

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"

📦 Grenzen

Halte Imports innerhalb der dokumentierten Abhängigkeitsrichtung — siehe die Architektur-Übersicht für das Diagramm und die Pro-Paket-Import-Tabelle. Die Kurzform:

dispatchatlas.core ist die innere Domänengrenze und importiert kein DispatchAtlas-Paket.
dispatchatlas.bench und dispatchatlas.solve hängen nur von core ab.
dispatchatlas.lab komponiert die Pakete core, benchmark, und solver.
dispatchatlas.analytica konsumiert die core-Verträge und stabile Manifeste.
site/ konsumiert genehmigte Exporte; tools/ und CI inspizieren jedes Paket, sind aber keine Produkt-Runtime-Abhängigkeiten.

Die Grenze wird durch tests/architecture/test_import_boundaries.py erzwungen, sodass ein kreuzender Import die Test-Suite vor der Review nicht besteht.

📋 Pull-Request-Erwartungen

Bereich	Erwartung
Code	Halte Imports innerhalb der dokumentierten Abhängigkeitsrichtung.
Daten	Behandle Kampagnenausgaben als generierten Beleg, nicht als Quelldateien.
Docs	Verwende Erstveröffentlichungs-DispatchAtlas-Sprache, halte Smoke-Belege beschriftet, und aktualisiere Seiten, wenn sich das benutzerseitige Verhalten ändert.
Tests	Füge Verhaltensassertionen für neue öffentliche Verträge hinzu; beschreibe erwartetes Verhalten, statt externe Struktur zu reproduzieren.
Sicherheit	Committe keine Anmeldedaten, privaten Belege, oder Deployment-Geheimnisse.
Generierte Artefakte	Halte Caches, Build-Ausgaben, Coverage-Berichte, Experiment-Ausgaben, und Prüfpunkte aus Git heraus, sofern eine Repository-Richtlinie sie nicht als verfolgte Quelle benennt.

🤝 Gemeinschaft und Support

Community-Kanäle, Issue-Formulare, und Diskussionskategorien sind auf der Community-Seite zusammengefasst. Der Beitrags-Lebenszyklus — vorschlagen, abstimmen, implementieren, prüfen, mergen — ist in GOVERNANCE.md festgehalten.