貢献ガイド

DispatchAtlas は、パッケージ境界、決定的エビデンス、リリースゲートされた公開主張を保つ変更を受け入れます。貢献はリポジトリ契約から書かれます — 外部のソースツリー、生成されたレポート、未公開の実験成果物からコピーされません。ルートの CONTRIBUTING.md が権威あるチェックリストです; このページはそれをコードベースにマッピングします。

🧭 あなたの道を選ぶ

各フォルダの境界ルールはルートの AGENTS.md に住み、各パッケージフォルダもそれ自身の README.md を携えます。

意図	道	どこ
ソルバーのバグを修正	ソルバーレジストリ、演算子、またはメタヒューリスティクス、加えて挙動テスト。	`packages/dispatchatlas-solve/`（その README 参照）と `tests/solve/`。
ベンチマークファミリーを追加	ジェネレーター、分類法エントリ、引用マトリクス行、カタログ配線。	`packages/dispatchatlas-bench/`（その README 参照）と `tests/bench/`。
ドメイン契約を拡張	内部境界のスケジューリングモデル、検証、来歴、またはシリアライゼーション。	`packages/dispatchatlas-core/`（その README 参照）と `tests/core/`。
キャンペーン実行を改善	設定、予算、チェックポイント、リトライ、環境キャプチャ。	`packages/dispatchatlas-lab/`（その README 参照）と `tests/lab/`。
分析エクスポートを拡張	統計、開示フィルタリング、エビデンスバンドル、ポータルデータセット、CLI。	`packages/dispatchatlas-analytica/`（その README 参照）と `tests/analytica/`。
ドキュメントを改善	Next.js ドキュメントスタック上のサイトページ。	`site/content/docs/`（`site/README.md` 参照）。
実行可能な例を追加	スモークスケールで設定可能、公開安全な例。	`examples/`（その README が例のバケットとルールを列挙）。
品質ツールを改善	build、prose-register、code-first、license-header ゲート。	`tools/`（その README 参照）と `tests/tools/`。
バグ報告や質問	構造化された issue フォームとサポートチャネル。	Issue フォームと `SUPPORT.md`。

⚙️ ローカルセットアップ

Python 3.12 以降をインストール。
uv をインストール。
uv sync --all-extras --group dev を実行。
ローカルコミットフックが欲しければ uv run pre-commit install を実行。

✅ ローカルチェック

pull request を開く前にこれらを実行 — ホスト型 CI は同じゲートセットを OS と 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

パッケージ-ビルドスモークチェック向け:

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"

📦 境界

import を文書化された依存方向の内側に保ってください — 図とパッケージごとの import テーブルについてはアーキテクチャ概要を参照。短い形:

dispatchatlas.core は内部ドメイン境界であり、いかなる DispatchAtlas パッケージも import しません。
dispatchatlas.bench と dispatchatlas.solve は core のみに依存します。
dispatchatlas.lab は core、benchmark、solver パッケージを構成します。
dispatchatlas.analytica は core 契約と安定マニフェストを消費します。
site/ は承認済みエクスポートを消費します; tools/ と CI は各パッケージを検査しますが、製品ランタイム依存ではありません。

境界は tests/architecture/test_import_boundaries.py によって強制されるため、横断する import はレビュー前にテストスイートを失敗させます。

📋 Pull request の期待

領域	期待
コード	import を文書化された依存方向の内側に保つ。
データ	キャンペーン出力を生成されたエビデンスとして扱い、ソースファイルとしない。
ドキュメント	初回-リリース DispatchAtlas 言語を使い、スモークエビデンスをラベル付きに保ち、ユーザー向け挙動が変わるときページを更新する。
テスト	新しい公開契約に挙動アサーションを追加; 外部構造を複製するのではなく期待される挙動を記述する。
セキュリティ	認証情報、私的エビデンス、またはデプロイ秘密をコミットしない。
生成成果物	リポジトリポリシーが追跡ソースとして名指ししない限り、キャッシュ、ビルド出力、カバレッジレポート、実験出力、チェックポイントを Git の外に保つ。

🤝 コミュニティとサポート

コミュニティチャネル、issue フォーム、ディスカッションカテゴリはコミュニティページに要約されています。貢献ライフサイクル — 提案、整合、実装、レビュー、マージ — は GOVERNANCE.md に記録されています。