From 787d0bb5eadd424a47279cf769f0c0b9b9a5d265 Mon Sep 17 00:00:00 2001 From: Anton Vakhrushev Date: Sun, 26 Jul 2026 22:01:38 +0300 Subject: [PATCH] =?UTF-8?q?guide:=20=D0=B8=D0=BC=D1=8F=20=D1=82=D0=B5?= =?UTF-8?q?=D0=BC=D1=8B=20=D0=B8=20=D0=BE=D0=B1=D1=8A=D1=8F=D0=B2=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=D0=BD=D0=B0=D1=8F=20=D0=BE=D1=81=D1=8C=20=E2=80=94?= =?UTF-8?q?=20META-37,=20META-38?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - META-37: тема называется решением и адресатом, а не ролью части проекта; логи сервера и браузера — logging и client-logging, а не суффиксная пара - META-38: ось слоя объявляется ключами lang/stack в шапке, а не выводится из пути — переезд файла между директориями иначе молча менял состав копии у каждого потребителя; шапки двенадцати конвенций приведены к правилу - в список проверок добавлены объявление оси, единственность базового слоя и совпадение объявленного с директорией --- GUIDE.md | 38 +++++++++++++++++++- LANGUAGE.md | 4 +++ conventions/lang/go/config.md | 1 + conventions/lang/go/db-identifiers.md | 1 + conventions/lang/go/db-schema.md | 1 + conventions/lang/go/errors.md | 1 + conventions/lang/go/logging.md | 1 + conventions/lang/go/time.md | 1 + conventions/stack/ansible/app-directories.md | 1 + conventions/stack/htmx/web-ui.md | 1 + 10 files changed, 49 insertions(+), 1 deletion(-) diff --git a/GUIDE.md b/GUIDE.md index 2696ab8..98b9722 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -65,13 +65,14 @@ prefix: META ## Как проверить границу темы -Готовая тема проходится по пяти вопросам; на каждый отвечает своё правило: +Готовая тема проходится по шести вопросам; на каждый отвечает своё правило: - на какой вопрос отвечает правило — и тот ли это вопрос, что у темы (META-33); - нужна ли тема правдоподобному потребителю целиком (META-34); - слой сужает базу или отменяет её (META-35); - зависит ли норма от вида приложения и назван ли он (META-36); +- названа ли тема решением и адресатом, а не ролью части проекта (META-37); - исполнима ли норма, если соседних тем в репозитории нет (META-20). Расхождение на любом из них означает, что граница проходит не там, где @@ -151,6 +152,41 @@ prefix: META его нарушаем» и записывает второе, хотя чинится первое — условие применимости в каноне (META-15.2). +### META-37. Имя темы называет решение и адресата, а не место в архитектуре + +**СЛЕДУЕТ.** Именем темы служит решение вместе с тем, кому оно адресовано, а +не роль части конкретного проекта. + +**ПОЧЕМУ.** Имя темы вечно и не переиспользуется (META-29): оно стоит в +`origin:` каждой копии, в подписках, в чужих ссылках. Роль же принадлежит +сегодняшнему устройству одного проекта — «фронтенд», который через три года +рендерится на сервере, называется по-прежнему, а означает другое, и заметить +расхождение нечем: имя ни на что не ссылается, кроме привычки. Пара имён вида +`logging-backend` и `logging-frontend` вдобавок навязывает чтение «две +разновидности одного», хотя по границе это две темы: серверную запись читают +постфактум инструментом, клиентскую — разработчик в консоли или сборщик ошибок +на той стороне сети, и общего у них остаётся три правила из сорока. Названные +по адресату — `logging` и `client-logging` — они и читаются как разные. +Ступень ниже высшей потому, что «решение против роли» — суждение о слове: на +границе двое разойдутся. + +### META-38. Ось слоя объявляется в шапке файла + +**ДОЛЖЕН.** Принадлежность слоя оси объявляется в шапке ключами `lang:` и +`stack:`, а не выводится из пути файла; отсутствие обоих ключей означает +базовый слой темы. + +**ПОЧЕМУ.** Ось, выведенная из пути, ломается тем же способом, что и тема, +выведенная из имени файла (META-28), только тише: переезд файла между +директориями не меняет ни одного идентификатора, но меняет состав копии у +каждого потребителя — слой начинает выбираться при другом языке или всегда. +Сверить это не с чем, потому что путь ничего не утверждает, а объявления нет. +Объявление вдобавок выражает то, чего дерево директорий не выражает: слой, +осмысленный только при совпадении языка и инструмента сразу; и набор, у +которого осей нет вовсе, перестаёт требовать директорий-заглушек. Дерево при +этом остаётся — но тем же, чем уже является `extends:`, документацией связи +для человека. + ### META-28. Тема объявляется в шапке файла и стоит в манифесте набора **ДОЛЖЕН.** Шапка несёт ключ `topic:` с именем темы, и это имя стоит в diff --git a/LANGUAGE.md b/LANGUAGE.md index c711123..68406ef 100644 --- a/LANGUAGE.md +++ b/LANGUAGE.md @@ -602,6 +602,10 @@ XMIG-6 не соблюдается в легаси-таблицах `show_histor - шапка файла несёт имя темы, и это имя стоит в манифесте набора — среди живых, а не среди выбывших; +- ось слоя объявлена в шапке, а не выведена из пути; у одной темы не больше + одного слоя без ключей оси — базовый слой единственный; +- если директории осей используются, объявленное в шапке совпадает с путём: + расхождение означает переезд файла без правки шапки; - имя темы, названное в ссылке или в подписке потребителя, тоже разрешается по манифесту: ссылка на снятую тему не проходит молча; - префиксы локальных правил копии начинаются на `X`; diff --git a/conventions/lang/go/config.md b/conventions/lang/go/config.md index dfd18f4..e44fe13 100644 --- a/conventions/lang/go/config.md +++ b/conventions/lang/go/config.md @@ -1,6 +1,7 @@ --- topic: config prefix: GCFG +lang: go extends: arch/config.md --- diff --git a/conventions/lang/go/db-identifiers.md b/conventions/lang/go/db-identifiers.md index 7a16dce..4e7b3ab 100644 --- a/conventions/lang/go/db-identifiers.md +++ b/conventions/lang/go/db-identifiers.md @@ -1,6 +1,7 @@ --- topic: db-identifiers prefix: GKEY +lang: go extends: arch/db-identifiers.md --- diff --git a/conventions/lang/go/db-schema.md b/conventions/lang/go/db-schema.md index c42064f..8acd236 100644 --- a/conventions/lang/go/db-schema.md +++ b/conventions/lang/go/db-schema.md @@ -1,6 +1,7 @@ --- topic: db-schema prefix: MIGR +lang: go --- # Схема и миграции (SQLite, Go) diff --git a/conventions/lang/go/errors.md b/conventions/lang/go/errors.md index 4277198..6f6fc1d 100644 --- a/conventions/lang/go/errors.md +++ b/conventions/lang/go/errors.md @@ -1,6 +1,7 @@ --- topic: errors prefix: GERR +lang: go --- # Ошибки diff --git a/conventions/lang/go/logging.md b/conventions/lang/go/logging.md index 3d0fcd7..7b93b44 100644 --- a/conventions/lang/go/logging.md +++ b/conventions/lang/go/logging.md @@ -1,6 +1,7 @@ --- topic: logging prefix: SLOG +lang: go extends: arch/time.md --- diff --git a/conventions/lang/go/time.md b/conventions/lang/go/time.md index a7afd16..68dbe9b 100644 --- a/conventions/lang/go/time.md +++ b/conventions/lang/go/time.md @@ -1,6 +1,7 @@ --- topic: time prefix: GTIM +lang: go extends: arch/time.md --- diff --git a/conventions/stack/ansible/app-directories.md b/conventions/stack/ansible/app-directories.md index 3e878a6..71f9ac2 100644 --- a/conventions/stack/ansible/app-directories.md +++ b/conventions/stack/ansible/app-directories.md @@ -1,6 +1,7 @@ --- topic: app-directories prefix: ANSD +stack: ansible extends: arch/app-directories.md --- diff --git a/conventions/stack/htmx/web-ui.md b/conventions/stack/htmx/web-ui.md index 62cc686..e9b7751 100644 --- a/conventions/stack/htmx/web-ui.md +++ b/conventions/stack/htmx/web-ui.md @@ -1,6 +1,7 @@ --- topic: web-ui prefix: HTMX +stack: htmx --- # Веб-UI на htmx