Руководство по вкладу

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`).
Добавить исполняемый пример	Smoke-масштабные, настраиваемые, безопасные-для-публики примеры.	`examples/` (его README перечисляет корзины примеров и правила).
Улучшить инструментарий качества	Gates 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, если хотите локальные commit-хуки.

✅ Локальные проверки

Выполните эти до открытия pull request — хостируемый CI прогоняет тот же набор gates через матрицу 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

Для smoke-проверок сборки пакетов:

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"

📦 Границы

Держите импорты внутри документированного направления зависимостей — см. обзор архитектуры для диаграммы и таблицы импортов по-пакетам. Краткая форма:

dispatchatlas.core — внутренняя доменная граница и не импортирует ни одного пакета DispatchAtlas.
dispatchatlas.bench и dispatchatlas.solve зависят только от core.
dispatchatlas.lab компонует пакеты core, benchmark, и solver.
dispatchatlas.analytica потребляет контракты core и стабильные манифесты.
site/ потребляет одобренные экспорты; tools/ и CI инспектируют каждый пакет, но не являются зависимостями времени выполнения продукта.

Граница обеспечивается tests/architecture/test_import_boundaries.py, так что пересекающий импорт проваливает набор тестов до проверки.

📋 Ожидания pull request

Область	Ожидание
Код	Держите импорты внутри документированного направления зависимостей.
Данные	Трактуйте выводы кампаний как сгенерированное доказательство, не файлы исходников.
Docs	Используйте язык DispatchAtlas первого-выпуска, держите smoke-доказательство помеченным, и обновляйте страницы, когда меняется пользовательское поведение.
Тесты	Добавляйте поведенческие утверждения для новых публичных контрактов; описывайте ожидаемое поведение, а не воспроизводите внешнюю структуру.
Безопасность	Не коммитьте учётные данные, частное доказательство, или секреты развёртывания.
Сгенерированные артефакты	Держите кэши, выводы сборки, отчёты покрытия, выводы экспериментов, и контрольные точки вне Git, если только политика репозитория не называет их отслеживаемым исходником.

🤝 Сообщество и поддержка

Каналы сообщества, формы issue, и категории обсуждений резюмированы на странице сообщества. Жизненный цикл вклада — предложить, согласовать, реализовать, проверить, слить — зафиксирован в GOVERNANCE.md.