темы: определение, объявление в шапке и манифест набора
- тема — набор правил об одном фокусе разработки, имя латиницей (нижний 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:
+34
-4
@@ -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` и не значится в списке выбывших;
|
||||
- шапка файла несёт имя темы, и это имя стоит в манифесте набора — среди
|
||||
живых, а не среди выбывших;
|
||||
- имя темы, названное в ссылке или в подписке потребителя, тоже разрешается по
|
||||
манифесту: ссылка на снятую тему не проходит молча;
|
||||
- заголовки правил файла используют только его собственный префикс;
|
||||
- номера уникальны внутри файла и не имеют пропусков вниз (новое правило
|
||||
берёт следующий свободный, а не первый освободившийся);
|
||||
|
||||
Reference in New Issue
Block a user