Repository Guidelines (для агентa и контрибьюторов)

Эта репа — учебный стенд для студентов (менти), которые только начинают с Airflow/Greenplum и Python. Пожалуйста, держите решения простыми, стабильными и хорошо объяснёнными.

Структура проекта

airflow/dags/ — DAG-файлы (например, csv_to_greenplum.py, data_quality_greenplum.py).
airflow/requirements.txt — зависимости, которые ставятся внутри контейнеров Airflow.
sql/ — DDL и вспомогательные SQL (например, sql/ddl_gp.sql).
docker-compose.yml — Greenplum, Airflow, Postgres (мета-БД).
Makefile — удобные команды для локальной работы.
.env(.example) — настройки окружения (реальные секреты не коммитим).

Команды (основные)

make up — поднять весь стек.
make airflow-init — инициализировать мета-БД Airflow и создать пользователя.
make logs — логи webserver и scheduler.
make ddl-gp — применить DDL к Greenplum.
make gp-psql — открыть psql в контейнере Greenplum от gpadmin.
make down — остановить и удалить тома (данные будут потеряны).

Пример: make up && make airflow-init, затем открыть http://localhost:8080.

Локальное Python‑окружение

Используем uv: достаточно uv sync (или make dev-sync) — подтянет Python, создаст .venv, установит зависимости.
make dev-setup полезен при смене версии Python (выполнит uv python install + uv python pin перед uv sync).
Проверки: make test, make lint, make fmt (выполняются через uv run).
Не используем pip install --user; если что‑то попало в user‑site — удалить pip uninstall <package> и проверить pip list --user.
В IDE выбираем интерпретатор из .venv.

Стиль кода

Python: PEP 8, 4 пробела, snake_case; dag_id — lower_snake_case.
Импорты: stdlib → third‑party → local, по одному модулю в строке.
SQL: ключевые слова UPPERCASE, идентификаторы snake_case, завершаем ;.
Форматирование: black (88 cols) и isort. Если не уверены — запустите make fmt.
Язык: комментарии, docstring и документацию — на русском; имена идентификаторов — на английском.

Тестирование

Тесты лежат в tests/ (pytest). Запуск: make test.
Есть юнит‑тесты для helpers/greenplum.py и smoke‑тесты DAG‑структуры (tests/test_dags_smoke.py).
Smoke‑тесты DAG автоматически пропускаются, если Airflow не установлен в venv.
Для ручного прогона стенда см. TESTING.md (пошаговый чек‑лист для студентов).

Pull Requests

Conventional Commits: feat:, fix:, docs:, chore:, refactor:. Пример: feat(dags): load orders to Greenplum.
Держите изменения минимальными и локальными. Не переименовывайте Make‑таргеты без обновления документации.
В описании PR добавляйте скрин DAG‑графа или логи задач, если менялась логика.
При изменении схемы/поведения — обновляйте README.md и sql/ddl_gp.sql.

Безопасность и конфигурация

Все настройки — через .env; креды в коде не хардкодим. Частые переменные: GP_*, PG_*, AIRFLOW_*, CSV_*.
make down удаляет тома — предупреждайте студентов, что данные пропадут.

Для агента (особенности аудитории)

Пишите простыми словами. Добавляйте короткие комментарии к нетривиальной логике.
Избегайте больших рефакторингов и сложных паттернов — студенты только начинают.
Ошибки и логи — дружелюбные и понятные (лучше с подсказкой «что сделать дальше»).
Перед релевантными правками валидируйте локально: make up && make airflow-init, затем откройте DAG в UI и/или прогоните make test.

5.1 KiB Raw Blame History Unescape Escape