diff --git a/.conventions-suite.toml b/.conventions-suite.toml index 7a6e8e9..fe72b2d 100644 --- a/.conventions-suite.toml +++ b/.conventions-suite.toml @@ -1,53 +1,12 @@ -# suite.toml — манифест набора конвенций. -# -# Манифестов в модели два, и каждый назван по тому, что описывает: -# -# - `suite.toml` здесь, в наборе, — сам набор: язык записи, темы, занятые -# префиксы правил; -# - `.conventions.toml` в проекте — подключение: откуда взяты копии, какие -# темы выбраны, какие язык и стек. -# -# По тому, какой из двух лежит рядом, видно, где ты находишься. -# -# Оба идентификатора набора — тема и префикс — живут здесь, потому что -# правила у них общие: объявляются в шапке файла, сверяются с манифестом, -# не переиспользуются никогда, а снятые уходят в свой раздел `retired` -# вместе с причиной и датой. - -# ─── Язык записи ──────────────────────────────────────────────────────────── -# -# Набор объявляет версию языка, на котором записаны его правила, и два -# документа о нём. Полное описание остаётся у автора; в копию рядом с -# конвенциями едет короткое `READING.md` — то, что нужно читателю правил, без -# ссылок на правила ведения набора. +governance = "GUIDE.md" [language] version = 1 +lang = "ru" description = "LANGUAGE.md" reading = "READING.md" -# ─── Темы ─────────────────────────────────────────────────────────────────── -# -# Тема — набор правил об одном фокусе разработки: время, конфигурация, схема -# БД. Имя записывается латиницей; рекомендуется нижний kebab-case, но годится -# любой идентификатор, пригодный для имени файла. -# -# Тема — единица подписки; собирается она на каждый компонент проекта, все -# слои темы в один файл в порядке база → язык → стек. Слои узнают друг друга -# по объявленному имени, а не по имени файла: файл конвенции несёт тему в -# шапке (`topic: time`), а свою ось — ключами `lang:` и `stack:` там же -# (META-38). Слой без ключей оси — базовый; тем, у которых слой один, -# директории осей не нужны вовсе. -# -# Имя темы не переименовывается и не переиспользуется: на тему ссылаются -# словом — из текста конвенций («конвенция `logging`»), из подписки в -# манифесте потребителя, из шапки `origin:` каждой копии, — и такая ссылка -# обязана продолжать указывать на тот же набор правил. Тема живёт, пока в -# `conventions/` есть хотя бы один её слой. -# -# Описание — одна строка о том, про что тема: из него собирается таблица в -# README директории конвенций у потребителя (META-18). - +[topics] [topics.live] app-directories = "категории директорий приложения и что в каждой лежит" config = "конфигурация: файл, валидация, секреты" @@ -58,60 +17,18 @@ logging = "логирование: уровни, структура записи time = "время: хранение, зоны, форматы, календарные границы" web-ui = "веб-UI: партиалы, свопы, поллинг" -[topics.retired] -# Пусто. Сюда попадают имена снятых и переименованных тем вместе с причиной -# и датой, чтобы их нельзя было выдать другой теме. - -# ─── Префиксы правил ──────────────────────────────────────────────────────── -# -# Префикс — четыре заглавные латинские буквы, уникальные по всему набору. Он -# выбирается под файл, а не выводится по формуле: префикс нужен, чтобы по нему -# искать, а не чтобы его разбирать. Поэтому подходящее слово лучше -# закономерности. -# -# Правила: -# -# - префикс не переименовывается и не переиспользуется никогда — ссылка -# из чужого репозитория обязана продолжать указывать на то же место; -# - при удалении или разделении файла префикс уходит в retired, а не -# освобождается; -# - переезд файла между осями префикс не меняет: идентификатор правила -# не зависит от таксономии; -# - вынос части правил в новый файл — это новый префикс и новая нумерация: -# перенос правила между документами есть смысловое изменение, а не -# переименование; -# - тот же префикс продублирован в шапке файла (`prefix:`), conv сверяет. -# -# Префикс принадлежит файлу, тема — набору файлов: у слоёв одной темы -# префиксы разные, а имя темы одно. -# -# Пути даются от корня репозитория, а не от `conventions/`: манифест покрывает -# и обвязку тоже. -# -# Буква `X` в начале префикса зарезервирована за репозиториями-потребителями: -# набор её не занимает никогда, локальные правила берут префиксы только на -# неё (XTIM, XLOG). Согласовывать их с манифестом не нужно — столкновение -# невозможно по построению. - +[prefixes] [prefixes.live] -DIRS = "conventions/arch/app-directories.md" -CONF = "conventions/arch/config.md" -KEYS = "conventions/arch/db-identifiers.md" -TIME = "conventions/arch/time.md" -GCFG = "conventions/lang/go/config.md" -GKEY = "conventions/lang/go/db-identifiers.md" -MIGR = "conventions/lang/go/db-schema.md" -GERR = "conventions/lang/go/errors.md" -SLOG = "conventions/lang/go/logging.md" -GTIM = "conventions/lang/go/time.md" ANSD = "conventions/stack/ansible/app-directories.md" +CONF = "conventions/arch/config.md" +DIRS = "conventions/arch/app-directories.md" +GCFG = "conventions/lang/go/config.md" +GERR = "conventions/lang/go/errors.md" +GKEY = "conventions/lang/go/db-identifiers.md" +GTIM = "conventions/lang/go/time.md" HTMX = "conventions/stack/htmx/web-ui.md" - -# Документ, которым канон ведёт себя сам: к потребителю не едет, но правила в -# нём записаны тем же языком, цитируются по номерам и проверяются как -# конвенция — отсюда префикс. Темы у него нет: подписаться на него нельзя. +KEYS = "conventions/arch/db-identifiers.md" META = "GUIDE.md" - -[prefixes.retired] -# Пусто. Сюда попадают префиксы удалённых и разделённых файлов вместе с -# причиной и датой, чтобы их нельзя было выдать повторно. +MIGR = "conventions/lang/go/db-schema.md" +SLOG = "conventions/lang/go/logging.md" +TIME = "conventions/arch/time.md" diff --git a/README.md b/README.md index 3d8c5e0..d6bab79 100644 --- a/README.md +++ b/README.md @@ -163,11 +163,17 @@ prefix: KEYS ``` Четыре заглавные латинские буквы, уникальные по всему канону; перечислены в -манифесте набора, секция `[prefixes.live]`. Префикс выбирается под файл, а не -выводится по формуле, и не переиспользуется никогда. Правила адресуются -идентификатором `KEYS-5` — без пути к файлу. Подробности формы — +манифесте набора, секция `[prefixes.live]`, путём **от корня репозитория**, а +не от `conventions/` — манифест покрывает и обвязку тоже. Префикс выбирается +под файл, а не выводится по формуле, и не переиспользуется никогда. Правила +адресуются идентификатором `KEYS-5` — без пути к файлу. Подробности формы — `LANGUAGE.md`. +`GUIDE.md` тоже несёт префикс и тоже проверяется как конвенция: правила в нём +записаны тем же языком и цитируются по номерам. Темы у него нет — подписаться +на него нельзя, к потребителю он не едет, — и манифест называет его отдельным +ключом `governance`, чтобы конвенция, потерявшая `topic`, не сошла за него. + Буква `X` в начале префикса зарезервирована за репозиториями: канон её не занимает никогда, а локальные правила потребителя берут префиксы только на неё (`XTIM`, `XLOG`). Так столкновение локального префикса с будущим