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

- тема — набор правил об одном фокусе разработки, имя латиницей (нижний
  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
+34 -4
View File
@@ -14,7 +14,7 @@ version: 1
Описание языка ни на один набор конвенций не опирается, поэтому все примеры
здесь — вымышленные правила с префиксами на `X` (`XKEY`, `XMIG`, `XLOG`).
Такие префиксы канон не занимает никогда, реестру они не принадлежат — значит
Такие префиксы канон не занимает никогда, в манифесте набора их нет — значит
пример не спутать с настоящим правилом, а перенумерация конвенций описание
языка не задевает.
@@ -219,7 +219,7 @@ Directives, Part 2, по одной форме записи на ступень,
Модальность живёт на **правиле**, а не на файле. Файловый статус
(`status: рекомендуемая` / `обязательная` в шапке) не используется: он
неизбежно врёт, потому что один файл смешивает жёсткие требования с
советами. В шапке остаются только `prefix` и `extends`.
советами. В шапке остаются только `topic`, `prefix` и `extends`.
## Словарь другого языка
@@ -385,6 +385,12 @@ Directives, Part 2, по одной форме записи на ступень,
## Идентификаторы
Идентификаторов в языке два: **правило** адресуется префиксом с номером,
**конвенция целиком** — именем темы. Ссылаться путём к файлу нельзя ни на то,
ни на другое.
**Правило.**
- Формат — `<ПРЕФИКС>-<номер>`: `XKEY-5`, `XLOG-27`. Префикс принадлежит
файлу, нумерация внутри файла сквозная и начинается с единицы.
- Строка таблицы, если на неё нужно ссылаться отдельно, — `XKEY-5.1`,
@@ -397,7 +403,7 @@ Directives, Part 2, по одной форме записи на ступень,
- **Идентификаторы стабильны и не переиспользуются.** Удалённое правило
оставляет дыру в нумерации; занимать её новым нельзя — иначе ссылка из
чужого репозитория начнёт указывать на другое утверждение. То же
относится к префиксам: выбывшие хранит `prefixes.toml`.
относится к префиксам: выбывшие хранит манифест набора.
- Префикс **выбирается под файл, а не выводится по формуле**: он нужен,
чтобы по нему искать, а не чтобы его разбирать. Выводимый префикс вдобавок
привязал бы идентификатор к таксономии, которую канон перестраивает, и
@@ -411,6 +417,25 @@ Directives, Part 2, по одной форме записи на ступень,
Порядок правил в файле выбирается по читаемости, не по номерам: номер — это
идентификатор, а не позиция.
**Тема.**
- **Тема — набор правил об одном фокусе разработки:** время, конфигурация,
схема БД. Она же — единица подписки: потребитель берёт тему целиком, а не
отдельные правила.
- Имя темы записывается латиницей. Рекомендуется нижний kebab-case
(`db-identifiers`), но годится любой идентификатор, пригодный для имени
файла: имя попадает и в файловую систему потребителя, и в его манифест.
- **Тему объявляет файл, а не файловая система.** Имя стоит в шапке
(`topic:`) и зарегистрировано в манифесте набора. Слои одной темы несут
одно и то же имя — по нему они и собираются в один документ, как бы ни
назывались их файлы.
- **Имя темы не переиспользуется** — как и префикс: оно живёт в шапке
`origin:` каждой копии, в подписке манифеста и в тексте ссылок, поэтому
снятое имя уходит в раздел выбывших манифеста, а не достаётся другой теме.
- Ссылка на конвенцию — имя темы (конвенция `logging`), ссылка на правило —
идентификатор (`XLOG-27`). Путь файла не употребляется ни там, ни там: в
собранной копии путей канона не существует.
## Что правилом не является
Заглавные модальные слова в этих частях **не употребляются** — иначе
@@ -454,8 +479,13 @@ XMIG-6 не соблюдается в легаси-таблицах `show_histor
- модальные и служебные слова принадлежат объявленному словарю канона, а не
смеси словарей;
- префикс в шапке файла совпадает с реестром, состоит из четырёх заглавных
- префикс в шапке файла совпадает с манифестом набора, состоит из четырёх
заглавных
латинских букв, не начинается на `X` и не значится в списке выбывших;
- шапка файла несёт имя темы, и это имя стоит в манифесте набора — среди
живых, а не среди выбывших;
- имя темы, названное в ссылке или в подписке потребителя, тоже разрешается по
манифесту: ссылка на снятую тему не проходит молча;
- заголовки правил файла используют только его собственный префикс;
- номера уникальны внутри файла и не имеют пропусков вниз (новое правило
берёт следующий свободный, а не первый освободившийся);