темы: определение, объявление в шапке и манифест набора

- тема — набор правил об одном фокусе разработки, имя латиницей (нижний
  kebab-case рекомендуется, годится любой идентификатор, пригодный для имени
  файла); определение в LANGUAGE.md и README.md
- заведены META-28 и META-29: тема объявляется в шапке (`topic:`), стоит в
  манифесте набора и не переиспользуется; `topic:` добавлен во все 12 файлов
- prefixes.toml и topics.toml слиты в manifest.toml — манифест набора против
  манифеста подключения `.conventions.toml`, разделы topics/prefixes с live
  и retired
This commit is contained in:
av
2026-07-26 15:27:55 +03:00
parent d5118336cb
commit c1cb240540
19 changed files with 274 additions and 126 deletions
+101
View File
@@ -0,0 +1,101 @@
# Манифест набора конвенций.
#
# Манифестов в модели два, и они отвечают на разные вопросы:
#
# - этот, в наборе, описывает сам набор: какие в нём темы и какие префиксы
# правил заняты;
# - `.conventions.toml` в репозитории-потребителе описывает подключение:
# откуда взяты копии, какие темы выбраны, какие язык и стек.
#
# Оба идентификатора набора — тема и префикс — живут здесь, потому что
# правила у них общие: объявляются в шапке файла, сверяются с манифестом,
# не переиспользуются никогда, а снятые уходят в свой раздел `retired`
# вместе с причиной и датой.
# ─── Темы ───────────────────────────────────────────────────────────────────
#
# Тема — набор правил об одном фокусе разработки: время, конфигурация, схема
# БД. Имя записывается латиницей; рекомендуется нижний 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]
# Пусто. Сюда попадают префиксы удалённых и разделённых файлов вместе с
# причиной и датой, чтобы их нельзя было выдать повторно.