From e4e5688775b97b5c70ea7be0829d7fa23cec915f Mon Sep 17 00:00:00 2001 From: Dmitry Dementiev Date: Sun, 9 Aug 2026 21:49:54 +0300 Subject: [PATCH] =?UTF-8?q?refactor(make):=20=D0=BF=D1=80=D0=B0=D0=B2?= =?UTF-8?q?=D0=BA=D0=B8=20=D0=BF=D0=BE=20=D1=85=D0=BE=D0=BB=D0=BE=D0=B4?= =?UTF-8?q?=D0=BD=D0=BE=D0=BC=D1=83=20=D1=80=D0=B5=D0=B2=D1=8C=D1=8E=20?= =?UTF-8?q?=D1=80=D0=B5=D0=B0=D0=BB=D0=B8=D0=B7=D0=B0=D1=86=D0=B8=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - половина критерия приёмки стояла не там, где решено: предупреждение о ручном равенстве версий ruff адресовано тому, кто правит лок в generator/, а лежало в корневом Makefile. - довод «генератор — отдельная сущность» был выписан трижды почти дословно. - Что: - равенство версий и охват корневой цели названы в карте проверок; три примечания к таблице собраны списком. - названа цена занижения target-version: даги бегут на 3.13 и модернизаций не получают. - шапка generator/Makefile вырезана, корневая сжата до строки, объяснение в ruff.toml укорочено. - формулировки в AGENTS.md и README поправлены. - Проверка: - make lint; make config-test — зелёные. - make -C generator lint; typecheck — зелёные; исходники генератора не менялись. Co-Authored-By: Claude Opus 5 --- AGENTS.md | 3 ++- Makefile | 7 ++----- README.md | 7 +++---- docs/architecture/testing.md | 17 ++++++++++++----- generator/Makefile | 4 ---- ruff.toml | 10 +++++----- 6 files changed, 24 insertions(+), 24 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8604d48..b812a73 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -79,7 +79,8 @@ Airflow) и названия из кода. Если для понятия ес - Python — только через `uv`; проверка и формат — `ruff`. Цель `make lint` есть за двумя дверями и охватывает разное: в корне — код стенда, в - `generator/` — код генератора. Правишь одно — зови ту. + `generator/` — код генератора. Правишь даги или Superset — зови корневую, + правишь генератор — зови из `generator/`. - Изменения держать минимальными и в границах задания. - Куда класть новую проверку, что утверждает каждая цель `make` и почему смоук обязан оставаться быстрым — [`docs/architecture/testing.md`](docs/architecture/testing.md). diff --git a/Makefile b/Makefile index 1e66406..2f5b8a4 100644 --- a/Makefile +++ b/Makefile @@ -3,9 +3,7 @@ GENERATOR_DAY ?= 0 GENERATOR_LIMIT ?= GENERATOR_SPEED ?= -# Цели корня — про стенд. Проверки генератора живут за своей дверью, в -# `generator/Makefile`: генератор — отдельная и заменяемая сущность со своим -# `pyproject.toml`, локом и образом, и цели у него свои. +# Цели корня — про стенд; проверки генератора — в `generator/Makefile`. .PHONY: up down clean ps logs smoke check-clickhouse check-services config-test lint generate-batch generate-live # --- Жизнь стенда --- @@ -47,8 +45,7 @@ config-test: # Пути названы вслух: без них ruff из корня прошёлся бы и по генератору, а у # того своя дверь и свой конфиг. Версия закреплена, потому что лока в корне # нет, а форматтер между версиями меняет вывод — иначе проверка однажды -# покраснела бы сама, без единой правки в репозитории. Держать её равной той, -# что в `generator/uv.lock`, приходится руками: сверять их некому. +# покраснела бы сама, без единой правки в репозитории. lint: uvx ruff@0.16.1 check dags infra/superset uvx ruff@0.16.1 format --check dags infra/superset diff --git a/README.md b/README.md index 0b61c29..a9e8475 100644 --- a/README.md +++ b/README.md @@ -141,10 +141,9 @@ ClickHouse, пока мир не доедет. Повторный `make up` за Спрашивают её двое. `make test` в `generator/` сверяет опись с тем, что собирается из кода сегодня: правка генератора меняет мир, и опись надо -пересобрать — `make inventory` там же. `make check-clickhouse` в корне -сверяет с описью то, что доехало до -`ods.event`, подневно. Хеш дня можно пересчитать и руками — это обычный -`sha256sum` файла, который пишет файловый приёмник: +пересобрать — `make inventory` там же. `make check-clickhouse` в корне сверяет +с описью то, что доехало до `ods.event`, подневно. Хеш дня можно пересчитать и +руками — это обычный `sha256sum` файла, который пишет файловый приёмник: ```bash uv run --project generator python -m clickstream_generator batch \ diff --git a/docs/architecture/testing.md b/docs/architecture/testing.md index ffddba9..ff21045 100644 --- a/docs/architecture/testing.md +++ b/docs/architecture/testing.md @@ -54,11 +54,18 @@ генератора, генераторная — ни одного файла стенда. Человек в корне видит зелёное и может решить, что зелёный весь репозиторий. -Список правил у обеих один, а строгость нет: правила `UP` предлагают синтаксис -настолько новый, насколько позволяет `target-version`, — у генератора это 3.14 -из `requires-python`, у стенда 3.10, младшая из версий Python в его образах. -Один и тот же файл может пройти корневую проверку и не пройти генераторную. -Довод и замер — в комментарии `ruff.toml`. +Три тонкости, которых не видно из таблицы: + +- **Список правил у дверей один, а строгость нет.** Правила `UP` предлагают + синтаксис настолько новый, насколько позволяет `target-version`: у генератора + это 3.14 из `requires-python`, у стенда 3.10 — столько у Superset, младшего из + его образов. Один и тот же файл может пройти корневую проверку и не пройти + генераторную. Довод и замер — в комментарии `ruff.toml`. +- **Версия ruff у корневой цели закреплена в самом вызове** (`uvx ruff@0.16.1`) + и равна той, что в `generator/uv.lock`. Равенство держится руками: обновили + лок — поправьте и вызов, сверять их некому. +- **Охват держат аргументы вызова, а не устройство дерева.** Python, + положенный вне двух названных в таблице путей, не проверит ни одна из дверей. **Корневого `typecheck` нет, и это решение, а не пропуск.** Проверке типов мало прочитать файл: чтобы понять `from airflow.sdk import dag`, ей нужен diff --git a/generator/Makefile b/generator/Makefile index f13ac4f..4097a78 100644 --- a/generator/Makefile +++ b/generator/Makefile @@ -1,7 +1,3 @@ -# Цели генератора. Дверь у него своя, потому что своя и сущность: пакет с -# собственными `pyproject.toml`, `uv.lock` и образом, заменяемый целиком -# (спека генератора, раздел 1). Отсюда и короткие имена — каталог уже сказал, -# о ком речь, и суффикс `-generator` был бы вторым разом про то же. .PHONY: lint typecheck test docs inventory # --- Проверки --- diff --git a/ruff.toml b/ruff.toml index 94733d6..7e7455f 100644 --- a/ruff.toml +++ b/ruff.toml @@ -2,17 +2,17 @@ # в `generator/pyproject.toml`: конфиг ruff ищется вверх по дереву от файла, # поэтому ближний к генератору выигрывает и этот его не подменяет. # -# Здесь отдельный файл, а не `pyproject.toml`, потому что пакета в корне нет: -# корневой `pyproject.toml` завёл бы в репозитории второй проект `uv` — с -# локом и окружением, — которого стенду не нужно. +# Отдельный файл, а не `pyproject.toml`: пакета в корне нет и заводить его +# ради настройки линтера незачем. # На каком Python побежит код, ruff сам не знает: у генератора он берёт ответ # из `requires-python`, а у стенда спрашивать некого — даги и Superset живут # внутри образов. Замер 9 августа 2026 года: `apache/airflow:3.3.0` несёт # Python 3.13.14, `apache/superset:6.1.0` — 3.10.20. Стоит младшая из двух, # иначе ruff предложил бы Superset синтаксис, которого его Python не знает. -# Совпадает со значением ruff по умолчанию, и записано именно поэтому: -# сменится умолчание — проверка не поедет следом молча. +# Даги за это платят: они бегут на 3.13, и модернизаций, доступных только там, +# ruff им не предложит. Значение совпадает с умолчанием ruff, и записано +# именно поэтому: сменится умолчание — проверка не поедет следом молча. target-version = "py310" [lint]