guide: имя темы и объявленная ось — META-37, META-38
- META-37: тема называется решением и адресатом, а не ролью части проекта; логи сервера и браузера — logging и client-logging, а не суффиксная пара - META-38: ось слоя объявляется ключами lang/stack в шапке, а не выводится из пути — переезд файла между директориями иначе молча менял состав копии у каждого потребителя; шапки двенадцати конвенций приведены к правилу - в список проверок добавлены объявление оси, единственность базового слоя и совпадение объявленного с директорией
This commit is contained in:
@@ -65,13 +65,14 @@ prefix: META
|
|||||||
|
|
||||||
## Как проверить границу темы
|
## Как проверить границу темы
|
||||||
|
|
||||||
Готовая тема проходится по пяти вопросам; на каждый отвечает своё правило:
|
Готовая тема проходится по шести вопросам; на каждый отвечает своё правило:
|
||||||
|
|
||||||
- на какой вопрос отвечает правило — и тот ли это вопрос, что у темы
|
- на какой вопрос отвечает правило — и тот ли это вопрос, что у темы
|
||||||
(META-33);
|
(META-33);
|
||||||
- нужна ли тема правдоподобному потребителю целиком (META-34);
|
- нужна ли тема правдоподобному потребителю целиком (META-34);
|
||||||
- слой сужает базу или отменяет её (META-35);
|
- слой сужает базу или отменяет её (META-35);
|
||||||
- зависит ли норма от вида приложения и назван ли он (META-36);
|
- зависит ли норма от вида приложения и назван ли он (META-36);
|
||||||
|
- названа ли тема решением и адресатом, а не ролью части проекта (META-37);
|
||||||
- исполнима ли норма, если соседних тем в репозитории нет (META-20).
|
- исполнима ли норма, если соседних тем в репозитории нет (META-20).
|
||||||
|
|
||||||
Расхождение на любом из них означает, что граница проходит не там, где
|
Расхождение на любом из них означает, что граница проходит не там, где
|
||||||
@@ -151,6 +152,41 @@ prefix: META
|
|||||||
его нарушаем» и записывает второе, хотя чинится первое — условие
|
его нарушаем» и записывает второе, хотя чинится первое — условие
|
||||||
применимости в каноне (META-15.2).
|
применимости в каноне (META-15.2).
|
||||||
|
|
||||||
|
### META-37. Имя темы называет решение и адресата, а не место в архитектуре
|
||||||
|
|
||||||
|
**СЛЕДУЕТ.** Именем темы служит решение вместе с тем, кому оно адресовано, а
|
||||||
|
не роль части конкретного проекта.
|
||||||
|
|
||||||
|
**ПОЧЕМУ.** Имя темы вечно и не переиспользуется (META-29): оно стоит в
|
||||||
|
`origin:` каждой копии, в подписках, в чужих ссылках. Роль же принадлежит
|
||||||
|
сегодняшнему устройству одного проекта — «фронтенд», который через три года
|
||||||
|
рендерится на сервере, называется по-прежнему, а означает другое, и заметить
|
||||||
|
расхождение нечем: имя ни на что не ссылается, кроме привычки. Пара имён вида
|
||||||
|
`logging-backend` и `logging-frontend` вдобавок навязывает чтение «две
|
||||||
|
разновидности одного», хотя по границе это две темы: серверную запись читают
|
||||||
|
постфактум инструментом, клиентскую — разработчик в консоли или сборщик ошибок
|
||||||
|
на той стороне сети, и общего у них остаётся три правила из сорока. Названные
|
||||||
|
по адресату — `logging` и `client-logging` — они и читаются как разные.
|
||||||
|
Ступень ниже высшей потому, что «решение против роли» — суждение о слове: на
|
||||||
|
границе двое разойдутся.
|
||||||
|
|
||||||
|
### META-38. Ось слоя объявляется в шапке файла
|
||||||
|
|
||||||
|
**ДОЛЖЕН.** Принадлежность слоя оси объявляется в шапке ключами `lang:` и
|
||||||
|
`stack:`, а не выводится из пути файла; отсутствие обоих ключей означает
|
||||||
|
базовый слой темы.
|
||||||
|
|
||||||
|
**ПОЧЕМУ.** Ось, выведенная из пути, ломается тем же способом, что и тема,
|
||||||
|
выведенная из имени файла (META-28), только тише: переезд файла между
|
||||||
|
директориями не меняет ни одного идентификатора, но меняет состав копии у
|
||||||
|
каждого потребителя — слой начинает выбираться при другом языке или всегда.
|
||||||
|
Сверить это не с чем, потому что путь ничего не утверждает, а объявления нет.
|
||||||
|
Объявление вдобавок выражает то, чего дерево директорий не выражает: слой,
|
||||||
|
осмысленный только при совпадении языка и инструмента сразу; и набор, у
|
||||||
|
которого осей нет вовсе, перестаёт требовать директорий-заглушек. Дерево при
|
||||||
|
этом остаётся — но тем же, чем уже является `extends:`, документацией связи
|
||||||
|
для человека.
|
||||||
|
|
||||||
### META-28. Тема объявляется в шапке файла и стоит в манифесте набора
|
### META-28. Тема объявляется в шапке файла и стоит в манифесте набора
|
||||||
|
|
||||||
**ДОЛЖЕН.** Шапка несёт ключ `topic:` с именем темы, и это имя стоит в
|
**ДОЛЖЕН.** Шапка несёт ключ `topic:` с именем темы, и это имя стоит в
|
||||||
|
|||||||
@@ -602,6 +602,10 @@ XMIG-6 не соблюдается в легаси-таблицах `show_histor
|
|||||||
|
|
||||||
- шапка файла несёт имя темы, и это имя стоит в манифесте набора — среди
|
- шапка файла несёт имя темы, и это имя стоит в манифесте набора — среди
|
||||||
живых, а не среди выбывших;
|
живых, а не среди выбывших;
|
||||||
|
- ось слоя объявлена в шапке, а не выведена из пути; у одной темы не больше
|
||||||
|
одного слоя без ключей оси — базовый слой единственный;
|
||||||
|
- если директории осей используются, объявленное в шапке совпадает с путём:
|
||||||
|
расхождение означает переезд файла без правки шапки;
|
||||||
- имя темы, названное в ссылке или в подписке потребителя, тоже разрешается по
|
- имя темы, названное в ссылке или в подписке потребителя, тоже разрешается по
|
||||||
манифесту: ссылка на снятую тему не проходит молча;
|
манифесту: ссылка на снятую тему не проходит молча;
|
||||||
- префиксы локальных правил копии начинаются на `X`;
|
- префиксы локальных правил копии начинаются на `X`;
|
||||||
|
|||||||
@@ -1,6 +1,7 @@
|
|||||||
---
|
---
|
||||||
topic: config
|
topic: config
|
||||||
prefix: GCFG
|
prefix: GCFG
|
||||||
|
lang: go
|
||||||
extends: arch/config.md
|
extends: arch/config.md
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -1,6 +1,7 @@
|
|||||||
---
|
---
|
||||||
topic: db-identifiers
|
topic: db-identifiers
|
||||||
prefix: GKEY
|
prefix: GKEY
|
||||||
|
lang: go
|
||||||
extends: arch/db-identifiers.md
|
extends: arch/db-identifiers.md
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -1,6 +1,7 @@
|
|||||||
---
|
---
|
||||||
topic: db-schema
|
topic: db-schema
|
||||||
prefix: MIGR
|
prefix: MIGR
|
||||||
|
lang: go
|
||||||
---
|
---
|
||||||
|
|
||||||
# Схема и миграции (SQLite, Go)
|
# Схема и миграции (SQLite, Go)
|
||||||
|
|||||||
@@ -1,6 +1,7 @@
|
|||||||
---
|
---
|
||||||
topic: errors
|
topic: errors
|
||||||
prefix: GERR
|
prefix: GERR
|
||||||
|
lang: go
|
||||||
---
|
---
|
||||||
|
|
||||||
# Ошибки
|
# Ошибки
|
||||||
|
|||||||
@@ -1,6 +1,7 @@
|
|||||||
---
|
---
|
||||||
topic: logging
|
topic: logging
|
||||||
prefix: SLOG
|
prefix: SLOG
|
||||||
|
lang: go
|
||||||
extends: arch/time.md
|
extends: arch/time.md
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -1,6 +1,7 @@
|
|||||||
---
|
---
|
||||||
topic: time
|
topic: time
|
||||||
prefix: GTIM
|
prefix: GTIM
|
||||||
|
lang: go
|
||||||
extends: arch/time.md
|
extends: arch/time.md
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -1,6 +1,7 @@
|
|||||||
---
|
---
|
||||||
topic: app-directories
|
topic: app-directories
|
||||||
prefix: ANSD
|
prefix: ANSD
|
||||||
|
stack: ansible
|
||||||
extends: arch/app-directories.md
|
extends: arch/app-directories.md
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -1,6 +1,7 @@
|
|||||||
---
|
---
|
||||||
topic: web-ui
|
topic: web-ui
|
||||||
prefix: HTMX
|
prefix: HTMX
|
||||||
|
stack: htmx
|
||||||
---
|
---
|
||||||
|
|
||||||
# Веб-UI на htmx
|
# Веб-UI на htmx
|
||||||
|
|||||||
Reference in New Issue
Block a user