ПОЧЕМУ стало ключевым словом, язык поднят до версии 2
- метка обоснования пишется заглавными и вошла в словарь набора: скелет правила теперь целиком из ключевых слов, а не смесь `**ДОЛЖЕН.**` и `**Почему.**`; в переводе на другой язык метка меняется как остальные слова (ПОЧЕМУ / WHY), 235 вхождений заменены - метки правила выделены из шкалы в отдельный перечень: ПОЧЕМУ и МЕХАНИЗИРОВАНО обязательности не задают, а размечают части, и стандартом не даются ни в одном языке — раньше МЕХАНИЗИРОВАНО висело строкой в таблице модальности - версия языка поднята до 2, потому что изменение формы меняет чтение уже написанного текста; строка о версии в двенадцати конвенциях перечисляет теперь и метки, а служебные слова сценария в неё по-прежнему не входят
This commit is contained in:
@@ -7,9 +7,9 @@ extends: arch/app-directories.md
|
||||
|
||||
Как категории из базового слоя раскладываются на сервере плейбуком.
|
||||
|
||||
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
|
||||
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
|
||||
только тогда, когда написаны заглавными.
|
||||
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и метки
|
||||
ПОЧЕМУ и МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 2 —
|
||||
тогда и только тогда, когда написаны заглавными.
|
||||
|
||||
## Область действия
|
||||
|
||||
@@ -27,7 +27,7 @@ extends: arch/app-directories.md
|
||||
состоит из нескольких директорий, имя даётся по содержимому (`media_dir`,
|
||||
`uploads_dir`, `dumps_dir`).
|
||||
|
||||
**Почему.** Переменная — единственная ссылка, которую разделяют задача
|
||||
**ПОЧЕМУ.** Переменная — единственная ссылка, которую разделяют задача
|
||||
создания директории и список бэкапа (ANSD-4). Литерал пути в одном из этих мест
|
||||
означает, что переименование директории молча разойдётся с бэкапом, и
|
||||
обнаружится это при восстановлении.
|
||||
@@ -36,7 +36,7 @@ extends: arch/app-directories.md
|
||||
|
||||
**СЛЕДУЕТ.** Список директорий в единственной задаче создания.
|
||||
|
||||
**Почему.** Этот список — единственное место, где декларировано всё, что
|
||||
**ПОЧЕМУ.** Этот список — единственное место, где декларировано всё, что
|
||||
приложение пишет на диск. Разнесённое по нескольким задачам создание
|
||||
отвечает на вопрос «какие директории есть у приложения» только чтением
|
||||
всего плейбука, а именно этот вопрос задают при заведении бэкапа и при
|
||||
@@ -48,7 +48,7 @@ extends: arch/app-directories.md
|
||||
(`app_owner_uid == app_owner_gid`) или общий `primary_user` — выбирается на
|
||||
репозиторий и фиксируется ниже.
|
||||
|
||||
**Почему.** Правило про соответствие владельца рантайму, а не про
|
||||
**ПОЧЕМУ.** Правило про соответствие владельца рантайму, а не про
|
||||
конкретную модель: приложение в контейнере пишет от определённого uid, и
|
||||
если директория принадлежит другому, отказ произойдёт не при деплое, а при
|
||||
первой записи — то есть после того, как плейбук отчитался об успехе. Выбор
|
||||
@@ -61,7 +61,7 @@ extends: arch/app-directories.md
|
||||
**ДОЛЖЕН.** Плейбук кладёт в `base_dir` файл `backup-targets`, строки
|
||||
которого ссылаются на переменные `*_dir` из ANSD-1, а не на литеральные пути.
|
||||
|
||||
**Почему.** Правило вывода списка механическое (ANSD-5), но применяет его
|
||||
**ПОЧЕМУ.** Правило вывода списка механическое (ANSD-5), но применяет его
|
||||
человек или шаблон — то есть ошибиться можно. Общая переменная делает целый
|
||||
класс ошибок невозможным: переименовал директорию — переименовалось в
|
||||
обоих местах. Независимо набранный список расходится тихо и проявляется в
|
||||
@@ -72,7 +72,7 @@ extends: arch/app-directories.md
|
||||
**ДОЛЖЕН.** Директории категории «данные», включая директорию дампов, — в
|
||||
списке; конфигурация и кеш — нет.
|
||||
|
||||
**Почему.** Реализация правила базовой конвенции. Кеш раздувает снапшот без
|
||||
**ПОЧЕМУ.** Реализация правила базовой конвенции. Кеш раздувает снапшот без
|
||||
пользы, а конфигурация содержит отрендеренные секреты — бэкап уезжает в
|
||||
облако, и источником истины для секретов остаётся vault, а не снапшот.
|
||||
|
||||
@@ -80,7 +80,7 @@ extends: arch/app-directories.md
|
||||
|
||||
**СЛЕДУЕТ.** В compose конфигурация подключается с `:ro`.
|
||||
|
||||
**Почему.** Плейбук — источник истины для конфигурации, и `:ro` превращает
|
||||
**ПОЧЕМУ.** Плейбук — источник истины для конфигурации, и `:ro` превращает
|
||||
это из договорённости в свойство системы: приложение, которое втихую
|
||||
переписывает свой конфиг, падает сразу, а не расходится с репозиторием
|
||||
незаметно. Приложение, которому запись в конфиг нужна по устройству,
|
||||
@@ -90,7 +90,7 @@ extends: arch/app-directories.md
|
||||
|
||||
**ДОЛЖЕН.** Файл не переносится во вложенную директорию.
|
||||
|
||||
**Почему.** Туда смотрит `project_src` модуля `docker_compose_v2`. Правило
|
||||
**ПОЧЕМУ.** Туда смотрит `project_src` модуля `docker_compose_v2`. Правило
|
||||
внешнее по происхождению, но нарушается легко — при попытке «навести
|
||||
порядок» и убрать compose в `config/`, где ему по смыслу категорий было бы
|
||||
место.
|
||||
@@ -100,7 +100,7 @@ extends: arch/app-directories.md
|
||||
**СЛЕДУЕТ.** Значения приходят из vault-переменных и попадают в файл,
|
||||
принадлежащий пользователю приложения.
|
||||
|
||||
**Почему.** Файл под `0600` не наследуется дочерними процессами, не виден в
|
||||
**ПОЧЕМУ.** Файл под `0600` не наследуется дочерними процессами, не виден в
|
||||
`docker inspect` и не оседает в compose-файле на диске. Это те же три
|
||||
довода, по которым базовая конвенция конфигурации выбирает файл вместо
|
||||
окружения.
|
||||
@@ -109,7 +109,7 @@ extends: arch/app-directories.md
|
||||
|
||||
**ДОПУСКАЕТСЯ.** Задача рендера идёт с `no_log: true`.
|
||||
|
||||
**Почему.** Явное разрешение нужно, чтобы ANSD-8 не читался как запрет на
|
||||
**ПОЧЕМУ.** Явное разрешение нужно, чтобы ANSD-8 не читался как запрет на
|
||||
деплой такого приложения. Способ вынужденный: секрет попадает в метаданные
|
||||
контейнера и в compose-файл на диске. Приложение, научившееся читать
|
||||
секреты из файла, переводится на ANSD-8 при ближайшем касании.
|
||||
|
||||
Reference in New Issue
Block a user