Panduan kontribusi

DispatchAtlas menerima perubahan yang mempertahankan batas paket, bukti deterministik, dan klaim publik ber-gate-rilis. Kontribusi ditulis dari kontrak repositori — tidak disalin dari pohon sumber eksternal, laporan yang dihasilkan, atau artefak eksperimen yang belum dipublikasikan. CONTRIBUTING.md akar adalah daftar periksa otoritatif; halaman ini memetakannya ke basis kode.

🧭 Pilih jalur Anda

Aturan batas setiap folder tinggal di AGENTS.md akar; setiap folder paket juga membawa README.md-nya sendiri.

Niat	Jalur	Di mana
Memperbaiki bug solver	Registry solver, operator, atau metaheuristik, plus pengujian perilaku.	`packages/dispatchatlas-solve/` (lihat README-nya) dan `tests/solve/`.
Menambah keluarga benchmark	Generator, entri taksonomi, baris matriks sitasi, pengawatan katalog.	`packages/dispatchatlas-bench/` (lihat README-nya) dan `tests/bench/`.
Memperluas kontrak domain	Model penjadwalan, validasi, provenans, atau serialisasi di batas dalam.	`packages/dispatchatlas-core/` (lihat README-nya) dan `tests/core/`.
Memperbaiki eksekusi kampanye	Konfigurasi, anggaran, checkpoint, percobaan-ulang, penangkapan lingkungan.	`packages/dispatchatlas-lab/` (lihat README-nya) dan `tests/lab/`.
Memperluas ekspor analisis	Statistik, penyaringan pengungkapan, paket bukti, kumpulan data portal, CLI.	`packages/dispatchatlas-analytica/` (lihat README-nya) dan `tests/analytica/`.
Memperbaiki dokumentasi	Halaman situs di stack dokumentasi Next.js.	`site/content/docs/` (lihat `site/README.md`).
Menambah contoh yang dapat dijalankan	Contoh skala-asap, dapat dikonfigurasi, aman-publik.	`examples/` (README-nya mendaftar ember contoh dan aturan).
Memperbaiki perkakas kualitas	Gate build, prose-register, code-first, dan license-header.	`tools/` (lihat README-nya) dan `tests/tools/`.
Melaporkan bug atau bertanya	Formulir issue terstruktur dan saluran dukungan.	Formulir issue dan `SUPPORT.md`.

⚙️ Penyiapan lokal

Pasang Python 3.12 atau lebih baru.
Pasang uv.
Jalankan uv sync --all-extras --group dev.
Jalankan uv run pre-commit install jika Anda ingin hook commit lokal.

✅ Pemeriksaan lokal

Jalankan ini sebelum membuka pull request — CI terkelola menjalankan set gate yang sama di seluruh matriks OS dan 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

Untuk pemeriksaan asap build paket:

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"

📦 Batas

Jaga import di dalam arah dependensi terdokumentasi — lihat ikhtisar arsitektur untuk diagram dan tabel import per-paket. Bentuk singkat:

dispatchatlas.core adalah batas domain dalam dan tidak meng-import paket DispatchAtlas mana pun.
dispatchatlas.bench dan dispatchatlas.solve bergantung hanya pada core.
dispatchatlas.lab menyusun paket core, benchmark, dan solver.
dispatchatlas.analytica mengonsumsi kontrak core dan manifes stabil.
site/ mengonsumsi ekspor yang disetujui; tools/ dan CI memeriksa setiap paket tetapi bukan dependensi runtime produk.

Batas ditegakkan oleh tests/architecture/test_import_boundaries.py, sehingga import yang menyeberang menggagalkan suite pengujian sebelum tinjauan.

📋 Ekspektasi pull request

Area	Ekspektasi
Kode	Jaga import di dalam arah dependensi terdokumentasi.
Data	Perlakukan keluaran kampanye sebagai bukti yang dihasilkan, bukan berkas sumber.
Dokumen	Gunakan bahasa DispatchAtlas rilis-pertama, jaga bukti asap tetap berlabel, dan perbarui halaman saat perilaku hadap-pengguna berubah.
Pengujian	Tambahkan asersi perilaku untuk kontrak publik baru; jelaskan perilaku yang diharapkan alih-alih mereproduksi struktur eksternal.
Keamanan	Jangan meng-commit kredensial, bukti privat, atau rahasia penyebaran.
Artefak yang dihasilkan	Jaga cache, keluaran build, laporan cakupan, keluaran eksperimen, dan checkpoint di luar Git kecuali kebijakan repositori menamainya sebagai sumber terlacak.

🤝 Komunitas dan dukungan

Saluran komunitas, formulir issue, dan kategori diskusi diringkas di halaman komunitas. Siklus hidup kontribusi — usulkan, selaraskan, implementasikan, tinjau, gabungkan — tercatat di GOVERNANCE.md.