diff --git a/common/conventions-guide.md b/GUIDE.md similarity index 99% rename from common/conventions-guide.md rename to GUIDE.md index a5c080f..bbaabb7 100644 --- a/common/conventions-guide.md +++ b/GUIDE.md @@ -5,7 +5,7 @@ принято», а не «что здесь происходит». Как записывается сама конвенция — правила, модальность, обоснования — в -[language.md](language.md). Здесь — про то, зачем конвенции заводятся, где +[LANGUAGE.md](LANGUAGE.md). Здесь — про то, зачем конвенции заводятся, где живут и как соотносятся с соседними видами документов. ## Область действия @@ -13,7 +13,7 @@ Правила ниже адресованы автору конвенции — тому, кто заводит новый файл или правит существующий, в каноне и в копиях репозиториев. Обязательность живёт на отдельном правиле, а не на файле; шкала модальных слов — в -[language.md](language.md). +[LANGUAGE.md](LANGUAGE.md). ## Отличие от соседей diff --git a/common/language.md b/LANGUAGE.md similarity index 100% rename from common/language.md rename to LANGUAGE.md diff --git a/README.md b/README.md index b85551d..340f25d 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,20 @@ `ansible-roles`: канон не источник истины во время работы, а лавка, из которой берут и в которую возвращают улучшения. +Сами конвенции лежат в `conventions/`, обвязка — в корне: + +| Файл | Что описывает | +|---|---| +| `README.md` | устройство канона, оси, синхронизация, жизненный цикл | +| [LANGUAGE.md](LANGUAGE.md) | язык записи правил: номера, модальность, «Почему» | +| [GUIDE.md](GUIDE.md) | как ведут конвенции: когда заводить, механизация, отступления | +| `conv` | синхронизация копий | + +Обвязка живёт только в каноне и в репозитории не оказывается — `conv` +синхронизирует лишь содержимое `conventions/`. Пока это осознанное +ограничение: копия конвенции ссылается на `LANGUAGE.md` как на внешний +документ. + Правило то же, что у ролей: **деплоится и читается только то, что лежит в git репозитория**. Канон никем не подключается на лету. @@ -30,12 +44,16 @@ git репозитория**. Канон никем не подключаетс ## Оси ``` -common/ как вести сами конвенции -arch/ решения, переживающие смену языка и инструментов -lang/<язык>/ как решение реализуется и механизируется в языке -stack/<стек>/ привязка к инструменту, хранилищу, транспорту +conventions/ + arch/ решения, переживающие смену языка и инструментов + lang/<язык>/ как решение реализуется и механизируется в языке + stack/<стек>/ привязка к инструменту, хранилищу, транспорту ``` +Пути правил даются относительно `conventions/`: адрес +`arch/db-identifiers.md R5`, а не `conventions/arch/…` — так же, как они +лягут в `docs/conventions/` репозитория. + Тест — по тому, замена чего убивает правило: > Умирает при смене **языка** → `lang/`. Умирает при смене **инструмента, diff --git a/conv b/conv index 971d88a..6c58355 100755 --- a/conv +++ b/conv @@ -1,9 +1,10 @@ #!/usr/bin/env python3 """conv — синхронизация конвенций между каноном и репозиторием. -Канон — эта директория. Репозиторий держит закоммиченные копии нужных -конвенций в docs/conventions/, повторяя структуру канона. Копия — источник -правды для репозитория; канон — лавка, из которой берут. +Канон — директория conventions/ рядом с этим скриптом. Репозиторий держит +закоммиченные копии нужных конвенций в docs/conventions/, повторяя её +структуру. Копия — источник правды для репозитория; канон — лавка, из +которой берут. Пути в origin даются относительно conventions/. Служебная разметка копии: @@ -50,8 +51,8 @@ import sys from pathlib import Path from typing import NoReturn -CANON = Path(__file__).resolve().parent -CANON_TREES = ("common", "arch", "lang", "stack") +CANON = Path(__file__).resolve().parent / "conventions" +CANON_TREES = ("arch", "lang", "stack") SERVICE_KEYS = ("origin", "origin_hash", "synced", "local") DEFAULT_DIR = "docs/conventions" ENC = "utf-8" diff --git a/arch/app-directories.md b/conventions/arch/app-directories.md similarity index 99% rename from arch/app-directories.md rename to conventions/arch/app-directories.md index 16652d9..8fa05c8 100644 --- a/arch/app-directories.md +++ b/conventions/arch/app-directories.md @@ -4,7 +4,7 @@ создания и ценности содержимого: конфигурация, данные, кеш. Категория сразу отвечает на два вопроса, которые иначе выясняются чтением кода приложения: **кто создаёт** содержимое и **что будет, если его потерять**. Из категорий -механически выводится состав бэкапа. Форма записи — `common/language.md`. +механически выводится состав бэкапа. Форма записи — `LANGUAGE.md`. ## Область действия diff --git a/arch/config.md b/conventions/arch/config.md similarity index 99% rename from arch/config.md rename to conventions/arch/config.md index c6dcfd5..36f26f9 100644 --- a/arch/config.md +++ b/conventions/arch/config.md @@ -1,7 +1,7 @@ # Конфигурация приложения Как устроена конфигурация: где лежит, как попадает в процесс, что с -секретами и когда падает. Форма записи — `common/language.md`. +секретами и когда падает. Форма записи — `LANGUAGE.md`. ## Область действия diff --git a/arch/db-identifiers.md b/conventions/arch/db-identifiers.md similarity index 99% rename from arch/db-identifiers.md rename to conventions/arch/db-identifiers.md index a90bd21..0d3f2a5 100644 --- a/arch/db-identifiers.md +++ b/conventions/arch/db-identifiers.md @@ -1,7 +1,7 @@ # Идентификаторы сущностей Как выбираются и как выглядят первичные ключи сущностей. Форма записи — -`common/language.md`. +`LANGUAGE.md`. ## Область действия diff --git a/arch/time.md b/conventions/arch/time.md similarity index 99% rename from arch/time.md rename to conventions/arch/time.md index 6a0fd14..349593f 100644 --- a/arch/time.md +++ b/conventions/arch/time.md @@ -2,7 +2,7 @@ Как приложение записывает моменты и длительности: в каком формате, откуда берётся значение и где появляется не-UTC. Форма записи — -`common/language.md`. +`LANGUAGE.md`. ## Область действия diff --git a/lang/go/config.md b/conventions/lang/go/config.md similarity index 99% rename from lang/go/config.md rename to conventions/lang/go/config.md index 0d97f83..2b01b25 100644 --- a/lang/go/config.md +++ b/conventions/lang/go/config.md @@ -5,7 +5,7 @@ extends: arch/config.md # Конфигурация: реализация на Go Как `arch/config.md` выглядит в Go-приложении: формат, загрузчик, границы -запрета на окружение. Форма записи — `common/language.md`. +запрета на окружение. Форма записи — `LANGUAGE.md`. Секретов Go-специфика не касается: они приходят из деплоя уже в файле, а проверка их непустоты идёт вместе с остальной валидацией — как описано в diff --git a/lang/go/db-identifiers.md b/conventions/lang/go/db-identifiers.md similarity index 99% rename from lang/go/db-identifiers.md rename to conventions/lang/go/db-identifiers.md index 0e273b5..ff38aed 100644 --- a/lang/go/db-identifiers.md +++ b/conventions/lang/go/db-identifiers.md @@ -5,7 +5,7 @@ extends: arch/db-identifiers.md # Идентификаторы: реализация на Go Как `arch/db-identifiers.md` выглядит в Go-приложении, выбравшем ULID -(ветка `arch/db-identifiers.md` R1.1). Форма записи — `common/language.md`. +(ветка `arch/db-identifiers.md` R1.1). Форма записи — `LANGUAGE.md`. Единая точка из `arch/db-identifiers.md` R3 — пакет `internal/ident`: он порождает идентификаторы (`NewID`, `NewIDAt`) и он же их разбирает diff --git a/lang/go/db-schema.md b/conventions/lang/go/db-schema.md similarity index 99% rename from lang/go/db-schema.md rename to conventions/lang/go/db-schema.md index 8f0a05d..3a98c0f 100644 --- a/lang/go/db-schema.md +++ b/conventions/lang/go/db-schema.md @@ -1,7 +1,7 @@ # Схема и миграции (SQLite, Go) Как пишутся миграции и какие типы колонок выбираются для схемы SQLite в -Go-приложении. Форма записи — `common/language.md`. +Go-приложении. Форма записи — `LANGUAGE.md`. ## Область действия diff --git a/lang/go/errors.md b/conventions/lang/go/errors.md similarity index 99% rename from lang/go/errors.md rename to conventions/lang/go/errors.md index 0ca68fd..21c479a 100644 --- a/lang/go/errors.md +++ b/conventions/lang/go/errors.md @@ -1,7 +1,7 @@ # Ошибки Как ошибки строятся, оборачиваются и проверяются. Форма записи — -`common/language.md`. Где и когда ошибку **логировать** — в +`LANGUAGE.md`. Где и когда ошибку **логировать** — в `lang/go/logging.md` (коротко: лог один раз на доменной границе). ## Правила diff --git a/lang/go/logging.md b/conventions/lang/go/logging.md similarity index 99% rename from lang/go/logging.md rename to conventions/lang/go/logging.md index 88fa1b7..e94e617 100644 --- a/lang/go/logging.md +++ b/conventions/lang/go/logging.md @@ -6,7 +6,7 @@ extends: arch/time.md Как и когда писать логи. Это правила оформления кода (How), а не спецификация поведения: наблюдаемые требования к логам, входящие в контракт -функциональности, живут в спеках. Форма записи — `common/language.md`. +функциональности, живут в спеках. Форма записи — `LANGUAGE.md`. Лог читают инструментами, а не глазами: повседневно — `jq` (`jq 'select(.download_id=="a1b2")' app.jsonl`), тяжёлое (агрегации, JOIN) — diff --git a/lang/go/time.md b/conventions/lang/go/time.md similarity index 99% rename from lang/go/time.md rename to conventions/lang/go/time.md index f5c864c..176f6d5 100644 --- a/lang/go/time.md +++ b/conventions/lang/go/time.md @@ -6,7 +6,7 @@ extends: arch/time.md Как требования `arch/time.md` выполняются в Go-коде: откуда берётся «сейчас», в каком виде время попадает в базу и в логи, что делать с зонами. -Форма записи — `common/language.md`. +Форма записи — `LANGUAGE.md`. ## Правила diff --git a/stack/ansible/app-directories.md b/conventions/stack/ansible/app-directories.md similarity index 99% rename from stack/ansible/app-directories.md rename to conventions/stack/ansible/app-directories.md index ab43607..c508d22 100644 --- a/stack/ansible/app-directories.md +++ b/conventions/stack/ansible/app-directories.md @@ -5,7 +5,7 @@ extends: arch/app-directories.md # Категории директорий: реализация в Ansible Как категории из `arch/app-directories.md` раскладываются на сервере -плейбуком. Форма записи — `common/language.md`. +плейбуком. Форма записи — `LANGUAGE.md`. ## Область действия diff --git a/stack/htmx/web-ui.md b/conventions/stack/htmx/web-ui.md similarity index 99% rename from stack/htmx/web-ui.md rename to conventions/stack/htmx/web-ui.md index 1903abd..9523d73 100644 --- a/stack/htmx/web-ui.md +++ b/conventions/stack/htmx/web-ui.md @@ -3,7 +3,7 @@ Как пишется код веб-UI: частичный своп фрагментов, поллинг живых обновлений, обработчики действий, деградация без JS, ошибки. Что именно UI показывает и какие действия поддерживает — в спеках, не здесь. Форма записи -— `common/language.md`. +— `LANGUAGE.md`. Логирование запросов — `lang/go/logging.md` (HTTP-поля, рутинно-частое на `DEBUG`). Трансляция доменных ошибок наружу — `lang/go/errors.md`