манифест приведён к машинному виду, объявлен governance
- добавлен ключ governance: без него конвенция, потерявшая topic, была неотличима от GUIDE.md и тихо теряла проверки об отъезде к потребителю - комментарии из манифеста убраны — их всё равно съела бы первая же команда; то, чего не было в README.md, дописано туда
This commit is contained in:
+14
-97
@@ -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"
|
||||
|
||||
@@ -163,11 +163,17 @@ prefix: KEYS
|
||||
```
|
||||
|
||||
Четыре заглавные латинские буквы, уникальные по всему канону; перечислены в
|
||||
манифесте набора, секция `[prefixes.live]`. Префикс выбирается под файл, а не
|
||||
выводится по формуле, и не переиспользуется никогда. Правила адресуются
|
||||
идентификатором `KEYS-5` — без пути к файлу. Подробности формы —
|
||||
манифесте набора, секция `[prefixes.live]`, путём **от корня репозитория**, а
|
||||
не от `conventions/` — манифест покрывает и обвязку тоже. Префикс выбирается
|
||||
под файл, а не выводится по формуле, и не переиспользуется никогда. Правила
|
||||
адресуются идентификатором `KEYS-5` — без пути к файлу. Подробности формы —
|
||||
`LANGUAGE.md`.
|
||||
|
||||
`GUIDE.md` тоже несёт префикс и тоже проверяется как конвенция: правила в нём
|
||||
записаны тем же языком и цитируются по номерам. Темы у него нет — подписаться
|
||||
на него нельзя, к потребителю он не едет, — и манифест называет его отдельным
|
||||
ключом `governance`, чтобы конвенция, потерявшая `topic`, не сошла за него.
|
||||
|
||||
Буква `X` в начале префикса зарезервирована за репозиториями: канон её не
|
||||
занимает никогда, а локальные правила потребителя берут префиксы только на
|
||||
неё (`XTIM`, `XLOG`). Так столкновение локального префикса с будущим
|
||||
|
||||
Reference in New Issue
Block a user