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

- тема — набор правил об одном фокусе разработки, имя латиницей (нижний
  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
+24 -40
View File
@@ -4,36 +4,17 @@
решения. Закрытый вопрос отсюда удаляется — принятое решение живёт в
`README.md`, `GUIDE.md` или `LANGUAGE.md`, а не в этом файле.
Две секции: сначала язык и подход, потом канон с тулингом. Пункты 1–6
Две секции: сначала язык и подход, потом канон с тулингом. Пункты 1–5
пришли из внешнего ревью описания языка и проверены по файлам на месте.
# Язык и подход
## 1. «Тема» — несущий идентификатор без определения и реестра
META-21 велит ссылаться на соседнюю конвенцию именем темы, манифест
подписывается `topics = ["time", …]`, сборка собирает файл темы из слоёв —
но нигде не сказано, что такое имя темы (имя файла без расширения?
отдельный атрибут в шапке?) и где список тем существует.
У префиксов есть реестр `prefixes.toml`, запрет переименования и запрет
переиспользования. У тем нет ничего: ссылка `KEYS-5` валидируется, ссылка
«конвенция `logging`» — нет, и в списке проверок её тоже нет. Переименование
файла темы тихо осиротит все текстовые ссылки во всех копиях.
Вопрос уже не гипотетический: пара `arch/db-identifiers.md` против
`lang/go/db-schema.md` (см. вопрос 10) показывает, что имена слоёв одной
темы могут не совпадать. Смежно: `extends: arch/time.md` у SLOG ломает
гарантию META-24 («базовый слой отсутствовать не может») — она верна только
для базы своей темы, а машинной проверке негде узнать тему, кроме имени
файла.
## 2. GUIDE выведен из-под проверок ложным основанием
## 1. GUIDE выведен из-под проверок ложным основанием
`LANGUAGE.md` исключает обвязку из проверок формулировкой «она ключевые слова
цитирует, а не употребляет». Для `GUIDE.md` это неверно: META-правила
употребляют ДОЛЖЕН нормативно, а префикс META зарегистрирован в `[live]`, где
прямо сказано, что правила записаны тем же языком.
употребляют ДОЛЖЕН нормативно, а префикс META стоит в `[prefixes.live]`
манифеста набора, где прямо сказано, что правила записаны тем же языком.
Три следствия. META-правила не попадают ни под одну проверку формы. В
`GUIDE.md` нет строки о версии языка, то есть у META-правил формально нет
@@ -44,7 +25,7 @@ META-21 велит ссылаться на соседнюю конвенцию
Честнее развести: `GUIDE.md` язык **употребляет** и проверяется как
конвенция, `LANGUAGE.md` и `README.md` — цитируют.
## 3. МЕХАНИЗИРОВАНО не переживает нового подписчика
## 2. МЕХАНИЗИРОВАНО не переживает нового подписчика
META-8 запрещает удалять норму, пока механизирована не у всех, и защищает
тем самым потребителей, существующих **на момент удаления**. Будущих не
@@ -62,7 +43,7 @@ META-8 запрещает удалять норму, пока механизир
в тексте канона, то есть ровно то, что запрещает META-4. Либо это законное
исключение, и тогда его надо назвать, либо конфликт.
## 4. Семантика ключевых слов в копию не едет
## 3. Семантика ключевых слов в копию не едет
Строка о версии языка перечисляет слова, но не их значения, а всё
нетривиальное в шкале живёт только в `LANGUAGE.md`, который в репозиторий не
@@ -78,7 +59,7 @@ META-8 запрещает удалять норму, пока механизир
копиями короткую выжимку семантики; расширить строку о версии до
двух-трёх предложений; или признать ограничение и записать его явно.
## 5. Две «механические» проверки без источника данных
## 4. Две «механические» проверки без источника данных
В списке «разбором текста» стоят два пункта, которые без дополнительного
реестра нерешаемы:
@@ -90,11 +71,12 @@ META-8 запрещает удалять норму, пока механизир
снятого номера в прозе выглядит как висячая ссылка.
`GUIDE.md` завёл для себя раздел «Освободившиеся номера», но язык не требует
такой таблицы от конвенций, а `prefixes.toml` хранит только префиксы. Пока
такой таблицы от конвенций, а манифест набора хранит только темы и префиксы.
Пока
реестр снятых номеров не объявлен частью языка, оба пункта принадлежат
списку «чтением».
## 6. Натяжки в опоре на стандарты
## 5. Натяжки в опоре на стандарты
Три места, где источнику приписано чуть больше, чем в нём есть:
@@ -113,7 +95,7 @@ META-8 запрещает удалять норму, пока механизир
Остальное в таблице проверку выдержало, включая вторую половину `MAY` из
BCP 14 и списки эквивалентных словесных форм ISO Directives.
## 7. Одиннадцать таблиц не прочитаны на взаимоисключительность
## 6. Одиннадцать таблиц не прочитаны на взаимоисключительность
`LANGUAGE.md` объявил, что строки таблицы решений взаимоисключающи по
умолчанию, а иной порядок объявляется явно. Объявление не делает таблицы
@@ -128,7 +110,7 @@ BCP 14 и списки эквивалентных словесных форм IS
Работа читательская, машине не даётся; в список проверок она уже записана в
разделе «Чтением, потому что машине не даётся».
## 8. Описание языка отдельно от набора конвенций
## 7. Описание языка отдельно от набора конвенций
`LANGUAGE.md` и `GUIDE.md` описывают, **как** пишутся конвенции;
`conventions/`**один конкретный** набор. Сейчас они склеены в одном
@@ -153,14 +135,14 @@ BCP 14 и списки эквивалентных словесных форм IS
# Канон, тулинг, подключение
## 9. Тулинг: две разные задачи в одном `conv`
## 8. Тулинг: две разные задачи в одном `conv`
Сейчас в `conv` смешаны две категории работы, и они расходятся по всему —
по частоте запуска, по тому, кто запускает, и по тому, что считается
провалом.
**Целостность канона.** Префиксы уникальны и не переиспользованы, шапка
совпадает с реестром, у каждого правила модальность и блок ПОЧЕМУ, ссылки
совпадает с манифестом, у каждого правила модальность и блок ПОЧЕМУ, ссылки
разрешаются, префикс чужой темы не лезет в норму (META-20), путей канона в
тексте нет (META-21), строка о версии языка на месте. Запускается в каноне,
при каждой правке, провал — это ошибка. Логика уже написана и много раз
@@ -184,7 +166,7 @@ BCP 14 и списки эквивалентных словесных форм IS
ссылках: это установка, а не целостность, но список подписок ему нужен из
манифеста.
Часть проверок из этого списка сейчас нереализуема по причине из вопроса 5,
Часть проверок из этого списка сейчас нереализуема по причине из вопроса 4,
так что порядок такой: сначала язык, потом чекер.
Перед тем как переписывать, стоит посмотреть на два готовых прототипа:
@@ -192,14 +174,16 @@ BCP 14 и списки эквивалентных словесных форм IS
манифеста и `vendir.yml` — как пример того, где проходит граница между «чего
хочу» и «что получил».
## 10. Пары слоёв и темы без базы
## 9. Пары слоёв и темы без базы
Отложено сознательно, но список стоит держать перед глазами:
- `SLOG` объявляет `extends: arch/time.md` — расширение **чужой** темы.
Сборщик темы `logging` на это наткнётся: базового слоя с темой `logging`
нет, а `arch/time.md` он тянуть не должен. Чинится переводом в обычную
ссылку «связано». Вдобавок это ломает гарантию META-24 — см. вопрос 1.
ссылку «связано». Вдобавок это ломает гарантию META-24: она верна только
для базы своей темы, а `arch/time.md` объявляет тему `time`, не `logging`.
С объявленной темой расхождение стало проверяемым машинно.
- Темы без арх-слоя: `db-schema`, `errors`, `web-ui`. Собираются в файл с
одной секцией — само по себе не ломается, но это и есть тот невыделенный
арх-слой из известного долга.
@@ -211,7 +195,7 @@ BCP 14 и списки эквивалентных словесных форм IS
- Вынос арх-ядра из `errors` и `logging` закроет две хрупкие ссылки из
`web-ui` (стек) в go-слой — единственные ссылки стек → язык в каноне.
## 11. Подключение к репозиториям
## 10. Подключение к репозиториям
Ничего ещё не подключено. Кандидаты — jellybit и pet-project-server.
Понадобится: заполнить локальную часть копий тем, что сейчас в этих
@@ -220,7 +204,7 @@ BCP 14 и списки эквивалентных словесных форм IS
строка в `AGENTS.md` каждого потребителя про то, что файлы в
`docs/conventions/` — копии.
## 12. Тулинг на Go, живущий независимо
## 11. Тулинг на Go, живущий независимо
Сейчас `conv` — питоновский скрипт внутри канона, то есть тулинг и данные в
одном репозитории и правятся одним движением. Мысль: вынести в отдельный
@@ -229,10 +213,10 @@ Go-бинарь со своим релизным циклом, ставить ч
Что за этим стоит помимо вкуса: независимый бинарь физически не даёт править
инструмент «заодно» с правкой конвенции, работает против **любого** канона и
любого потребителя — что прямо требуется вопросом 8, — и снимает питон из
любого потребителя — что прямо требуется вопросом 7, — и снимает питон из
зависимостей репозиториев-потребителей.
Порядок обратный ожидаемому: пока вопрос 8 не сделан, инструмент всё равно
Порядок обратный ожидаемому: пока вопрос 7 не сделан, инструмент всё равно
работает против одного конкретного канона, и независимый релизный цикл ему
нечего обслуживать. Сначала 8, потом 12. Разделение из вопроса 9 при этом
нечего обслуживать. Сначала 7, потом 11. Разделение из вопроса 8 при этом
дешевле заложить сразу, чем отпиливать потом.