기여 가이드

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 에 기록되어 있습니다.