av
170c06c1da
- заведён READING.md: словарь со значениями, форма правила и её граница, ссылки, локальная часть — без разделов о ведении набора и без META-ссылок, примеры на X-префиксах - сборщик кладёт его в docs/conventions/ и перезаписывает целиком; в манифест набора добавлена секция [language] с версией и двумя документами - META-30: правка словаря или состава частей правила доходит до READING.md, иначе потребитель толкует ДОПУСКАЕТСЯ по прежней версии
114 lines
8.2 KiB
TOML
114 lines
8.2 KiB
TOML
# Манифест набора конвенций.
|
|
#
|
|
# Манифестов в модели два, и они отвечают на разные вопросы:
|
|
#
|
|
# - этот, в наборе, описывает сам набор: какие в нём темы и какие префиксы
|
|
# правил заняты;
|
|
# - `.conventions.toml` в репозитории-потребителе описывает подключение:
|
|
# откуда взяты копии, какие темы выбраны, какие язык и стек.
|
|
#
|
|
# Оба идентификатора набора — тема и префикс — живут здесь, потому что
|
|
# правила у них общие: объявляются в шапке файла, сверяются с манифестом,
|
|
# не переиспользуются никогда, а снятые уходят в свой раздел `retired`
|
|
# вместе с причиной и датой.
|
|
|
|
# ─── Язык записи ────────────────────────────────────────────────────────────
|
|
#
|
|
# Набор объявляет версию языка, на котором записаны его правила, и два
|
|
# документа о нём. Полное описание остаётся у автора; в копию рядом с
|
|
# конвенциями едет короткое `READING.md` — то, что нужно читателю правил, без
|
|
# ссылок на правила ведения набора.
|
|
|
|
[language]
|
|
version = 1
|
|
description = "LANGUAGE.md"
|
|
reading = "READING.md"
|
|
|
|
# ─── Темы ───────────────────────────────────────────────────────────────────
|
|
#
|
|
# Тема — набор правил об одном фокусе разработки: время, конфигурация, схема
|
|
# БД. Имя записывается латиницей; рекомендуется нижний kebab-case, но годится
|
|
# любой идентификатор, пригодный для имени файла.
|
|
#
|
|
# Тема — единица подписки и единица сборки: потребитель перечисляет темы в
|
|
# своём манифесте, а сборщик складывает в один файл все слои темы в порядке
|
|
# arch → язык → стек. Слои узнают друг друга по объявленному имени, а не по
|
|
# имени файла: файл конвенции несёт тему в шапке (`topic: time`).
|
|
#
|
|
# Имя темы не переименовывается и не переиспользуется: на тему ссылаются
|
|
# словом — из текста конвенций («конвенция `logging`»), из подписки в
|
|
# манифесте потребителя, из шапки `origin:` каждой копии, — и такая ссылка
|
|
# обязана продолжать указывать на тот же набор правил. Тема живёт, пока в
|
|
# `conventions/` есть хотя бы один её слой.
|
|
#
|
|
# Описание — одна строка о том, про что тема: из него собирается таблица в
|
|
# README директории конвенций у потребителя (META-18).
|
|
|
|
[topics.live]
|
|
app-directories = "категории директорий приложения и что в каждой лежит"
|
|
config = "конфигурация: файл, валидация, секреты"
|
|
db-identifiers = "идентификаторы сущностей: вид ключа, генерация, границы"
|
|
db-schema = "схема БД и миграции: типы колонок, форма изменения"
|
|
errors = "ошибки: обёртки, границы трансляции, паники"
|
|
logging = "логирование: уровни, структура записи, что не логируем"
|
|
time = "время: хранение, зоны, форматы, календарные границы"
|
|
web-ui = "веб-UI: партиалы, свопы, поллинг"
|
|
|
|
[topics.retired]
|
|
# Пусто. Сюда попадают имена снятых и переименованных тем вместе с причиной
|
|
# и датой, чтобы их нельзя было выдать другой теме.
|
|
|
|
# ─── Префиксы правил ────────────────────────────────────────────────────────
|
|
#
|
|
# Префикс — четыре заглавные латинские буквы, уникальные по всему набору. Он
|
|
# выбирается под файл, а не выводится по формуле: префикс нужен, чтобы по нему
|
|
# искать, а не чтобы его разбирать. Поэтому подходящее слово лучше
|
|
# закономерности.
|
|
#
|
|
# Правила:
|
|
#
|
|
# - префикс не переименовывается и не переиспользуется никогда — ссылка
|
|
# из чужого репозитория обязана продолжать указывать на то же место;
|
|
# - при удалении или разделении файла префикс уходит в retired, а не
|
|
# освобождается;
|
|
# - переезд файла между осями префикс не меняет: идентификатор правила
|
|
# не зависит от таксономии;
|
|
# - вынос части правил в новый файл — это новый префикс и новая нумерация:
|
|
# перенос правила между документами есть смысловое изменение, а не
|
|
# переименование;
|
|
# - тот же префикс продублирован в шапке файла (`prefix:`), conv сверяет.
|
|
#
|
|
# Префикс принадлежит файлу, тема — набору файлов: у слоёв одной темы
|
|
# префиксы разные, а имя темы одно.
|
|
#
|
|
# Пути даются от корня репозитория, а не от `conventions/`: манифест покрывает
|
|
# и обвязку тоже.
|
|
#
|
|
# Буква `X` в начале префикса зарезервирована за репозиториями-потребителями:
|
|
# набор её не занимает никогда, локальные правила берут префиксы только на
|
|
# неё (XTIM, XLOG). Согласовывать их с манифестом не нужно — столкновение
|
|
# невозможно по построению.
|
|
|
|
[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"
|
|
HTMX = "conventions/stack/htmx/web-ui.md"
|
|
|
|
# Документ, которым канон ведёт себя сам: к потребителю не едет, но правила в
|
|
# нём записаны тем же языком, цитируются по номерам и проверяются как
|
|
# конвенция — отсюда префикс. Темы у него нет: подписаться на него нельзя.
|
|
META = "GUIDE.md"
|
|
|
|
[prefixes.retired]
|
|
# Пусто. Сюда попадают префиксы удалённых и разделённых файлов вместе с
|
|
# причиной и датой, чтобы их нельзя было выдать повторно.
|