язык записи опёрт на стандарты, словарь стал параметром
- шкала обязательности объявлена инвариантом, а набор ключевых слов — параметром естественного языка набора: для английского готовый словарь даёт BCP 14, для прочих берут перевод стандарта или делают свой; отклонены синонимы ступеней и `SHALL`, занятый OpenSpec - применены шесть дельт: нормативно только заглавное написание (RFC 8174), ДОЛЖЕН требует названного вреда и машинной проверки сразу, ДОПУСКАЕТСЯ адресовано рецензенту, МЕХАНИЗИРОВАНО выведено из шкалы в отметку рядом с модальностью (ISO/IEC/IEEE 29148), у таблиц объявлены политика совпадения и полнота (DMN) - «Форма записи — LANGUAGE.md» в двенадцати конвенциях заменена строкой о версии языка по образцу boilerplate BCP 14: пути канона в копии не существует, а словарь и правило заглавных строка несёт сама
This commit is contained in:
@@ -8,7 +8,11 @@ prefix: DIRS
|
||||
создания и ценности содержимого: конфигурация, данные, кеш. Категория сразу
|
||||
отвечает на два вопроса, которые иначе выясняются чтением кода приложения:
|
||||
**кто создаёт** содержимое и **что будет, если его потерять**. Из категорий
|
||||
механически выводится состав бэкапа. Форма записи — `LANGUAGE.md`.
|
||||
механически выводится состав бэкапа.
|
||||
|
||||
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
|
||||
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
|
||||
только тогда, когда написаны заглавными.
|
||||
|
||||
## Область действия
|
||||
|
||||
|
||||
@@ -5,7 +5,11 @@ prefix: CONF
|
||||
# Конфигурация приложения
|
||||
|
||||
Как устроена конфигурация: где лежит, как попадает в процесс, что с
|
||||
секретами и когда падает. Форма записи — `LANGUAGE.md`.
|
||||
секретами и когда падает.
|
||||
|
||||
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
|
||||
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
|
||||
только тогда, когда написаны заглавными.
|
||||
|
||||
## Область действия
|
||||
|
||||
|
||||
@@ -4,8 +4,11 @@ prefix: KEYS
|
||||
|
||||
# Идентификаторы сущностей
|
||||
|
||||
Как выбираются и как выглядят первичные ключи сущностей. Форма записи —
|
||||
`LANGUAGE.md`.
|
||||
Как выбираются и как выглядят первичные ключи сущностей.
|
||||
|
||||
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
|
||||
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
|
||||
только тогда, когда написаны заглавными.
|
||||
|
||||
## Область действия
|
||||
|
||||
|
||||
@@ -5,8 +5,11 @@ prefix: TIME
|
||||
# Время
|
||||
|
||||
Как приложение записывает моменты и длительности: в каком формате, откуда
|
||||
берётся значение и где появляется не-UTC. Форма записи —
|
||||
`LANGUAGE.md`.
|
||||
берётся значение и где появляется не-UTC.
|
||||
|
||||
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
|
||||
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
|
||||
только тогда, когда написаны заглавными.
|
||||
|
||||
## Область действия
|
||||
|
||||
|
||||
@@ -6,7 +6,11 @@ extends: arch/config.md
|
||||
# Конфигурация: реализация на Go
|
||||
|
||||
Как базовый слой выглядит в Go-приложении: формат, загрузчик, границы
|
||||
запрета на окружение. Форма записи — `LANGUAGE.md`.
|
||||
запрета на окружение.
|
||||
|
||||
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
|
||||
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
|
||||
только тогда, когда написаны заглавными.
|
||||
|
||||
Секретов Go-специфика не касается: они приходят из деплоя уже в файле, а
|
||||
проверка их непустоты идёт вместе с остальной валидацией — как описано в
|
||||
|
||||
@@ -5,8 +5,11 @@ extends: arch/db-identifiers.md
|
||||
|
||||
# Идентификаторы: реализация на Go
|
||||
|
||||
Как базовый слой выглядит в Go-приложении. Форма записи —
|
||||
`LANGUAGE.md`.
|
||||
Как базовый слой выглядит в Go-приложении.
|
||||
|
||||
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
|
||||
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
|
||||
только тогда, когда написаны заглавными.
|
||||
|
||||
Единая точка из `KEYS-3` — пакет `internal/ident`: он
|
||||
порождает идентификаторы (`NewID`, `NewIDAt`) и он же их разбирает
|
||||
|
||||
@@ -5,7 +5,11 @@ prefix: MIGR
|
||||
# Схема и миграции (SQLite, Go)
|
||||
|
||||
Как пишутся миграции и какие типы колонок выбираются для схемы SQLite в
|
||||
Go-приложении. Форма записи — `LANGUAGE.md`.
|
||||
Go-приложении.
|
||||
|
||||
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
|
||||
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
|
||||
только тогда, когда написаны заглавными.
|
||||
|
||||
## Область действия
|
||||
|
||||
|
||||
@@ -4,9 +4,13 @@ prefix: GERR
|
||||
|
||||
# Ошибки
|
||||
|
||||
Как ошибки строятся, оборачиваются и проверяются. Форма записи —
|
||||
`LANGUAGE.md`. Где и когда ошибку **логировать** — в конвенции `logging`
|
||||
(коротко: лог один раз на доменной границе).
|
||||
Как ошибки строятся, оборачиваются и проверяются. Где и когда ошибку
|
||||
**логировать** — в конвенции `logging` (коротко: лог один раз на доменной
|
||||
границе).
|
||||
|
||||
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
|
||||
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
|
||||
только тогда, когда написаны заглавными.
|
||||
|
||||
Две границы, о которых говорят правила ниже:
|
||||
|
||||
|
||||
@@ -7,7 +7,11 @@ extends: arch/time.md
|
||||
|
||||
Как и когда писать логи. Это правила оформления кода (How), а не
|
||||
спецификация поведения: наблюдаемые требования к логам, входящие в контракт
|
||||
функциональности, живут в спеках. Форма записи — `LANGUAGE.md`.
|
||||
функциональности, живут в спеках.
|
||||
|
||||
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
|
||||
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
|
||||
только тогда, когда написаны заглавными.
|
||||
|
||||
Лог читают инструментами, а не глазами: повседневно — `jq`
|
||||
(`jq 'select(.download_id=="a1b2")' app.jsonl`), тяжёлое (агрегации, JOIN) —
|
||||
|
||||
@@ -5,9 +5,12 @@ extends: arch/time.md
|
||||
|
||||
# Время: реализация на Go
|
||||
|
||||
Как требования базового слоя выполняются в Go-коде: откуда берётся
|
||||
«сейчас», в каком виде время попадает в базу и в логи, что делать с зонами.
|
||||
Форма записи — `LANGUAGE.md`.
|
||||
Как требования базового слоя выполняются в Go-коде: откуда берётся «сейчас»,
|
||||
в каком виде время попадает в базу и в логи, что делать с зонами.
|
||||
|
||||
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
|
||||
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
|
||||
только тогда, когда написаны заглавными.
|
||||
|
||||
## Правила
|
||||
|
||||
|
||||
@@ -5,8 +5,11 @@ extends: arch/app-directories.md
|
||||
|
||||
# Категории директорий: реализация в Ansible
|
||||
|
||||
Как категории из базового слоя раскладываются на сервере
|
||||
плейбуком. Форма записи — `LANGUAGE.md`.
|
||||
Как категории из базового слоя раскладываются на сервере плейбуком.
|
||||
|
||||
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
|
||||
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
|
||||
только тогда, когда написаны заглавными.
|
||||
|
||||
## Область действия
|
||||
|
||||
|
||||
@@ -4,10 +4,13 @@ prefix: HTMX
|
||||
|
||||
# Веб-UI на htmx
|
||||
|
||||
Как пишется код веб-UI: частичный своп фрагментов, поллинг живых
|
||||
обновлений, обработчики действий, деградация без JS, ошибки. Что именно UI
|
||||
показывает и какие действия поддерживает — в спеках, не здесь. Форма записи
|
||||
— `LANGUAGE.md`.
|
||||
Как пишется код веб-UI: частичный своп фрагментов, поллинг живых обновлений,
|
||||
обработчики действий, деградация без JS, ошибки. Что именно UI показывает и
|
||||
какие действия поддерживает — в спеках, не здесь.
|
||||
|
||||
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
|
||||
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
|
||||
только тогда, когда написаны заглавными.
|
||||
|
||||
Логирование запросов — конвенция `logging` (HTTP-поля, рутинно-частое на
|
||||
`DEBUG`). Трансляция доменных ошибок наружу — конвенция `errors`
|
||||
|
||||
Reference in New Issue
Block a user