язык: короткое описание для читателя копии едет в репозиторий

- заведён READING.md: словарь со значениями, форма правила и её граница,
  ссылки, локальная часть — без разделов о ведении набора и без META-ссылок,
  примеры на X-префиксах
- сборщик кладёт его в docs/conventions/ и перезаписывает целиком; в манифест
  набора добавлена секция [language] с версией и двумя документами
- META-30: правка словаря или состава частей правила доходит до READING.md,
  иначе потребитель толкует ДОПУСКАЕТСЯ по прежней версии
This commit is contained in:
av
2026-07-26 15:51:54 +03:00
parent 67d51db212
commit 170c06c1da
7 changed files with 205 additions and 39 deletions
+15 -30
View File
@@ -4,28 +4,12 @@
решения. Закрытый вопрос отсюда удаляется — принятое решение живёт в
`README.md`, `GUIDE.md` или `LANGUAGE.md`, а не в этом файле.
Две секции: сначала язык и подход, потом канон с тулингом. Пункты 1–3
Две секции: сначала язык и подход, потом канон с тулингом. Пункты 1–2
пришли из внешнего ревью описания языка и проверены по файлам на месте.
# Язык и подход
## 1. Семантика ключевых слов в копию не едет
Строка о версии языка перечисляет слова, но не их значения, а всё
нетривиальное в шкале живёт только в `LANGUAGE.md`, который в репозиторий не
едет: что ДОПУСКАЕТСЯ запрещает возражать на ревью, что отступление от
ДОЛЖЕН требует записи, что отступление от СЛЕДУЕТ требует причины.
Аналогия с BCP 14 ломается именно там, где призвана работать: RFC 2119
общедоступен и общеизвестен, «язык конвенций версии 1» — нет. Агент в
репозитории-потребителе прочитает ДОПУСКАЕТСЯ как бытовое «можно» и примет
возражение на ревью — ровно та потеря, ради которой слово вводилось.
Для одного автора терпимо, для агентов — нет. Варианты: возить рядом с
копиями короткую выжимку семантики; расширить строку о версии до
двух-трёх предложений; или признать ограничение и записать его явно.
## 2. Две «механические» проверки без источника данных
## 1. Две «механические» проверки без источника данных
В списке «разбором текста» стоят два пункта, которые без дополнительного
реестра нерешаемы:
@@ -42,7 +26,7 @@
требуют, а манифест набора хранит только темы и префиксы. Пока реестр снятых
номеров не объявлен частью языка, оба пункта принадлежат списку «чтением».
## 3. Натяжки в опоре на стандарты
## 2. Натяжки в опоре на стандарты
Три места, где источнику приписано чуть больше, чем в нём есть:
@@ -61,7 +45,7 @@
Остальное в таблице проверку выдержало, включая вторую половину `MAY` из
BCP 14 и списки эквивалентных словесных форм ISO Directives.
## 4. Одиннадцать таблиц не прочитаны на взаимоисключительность
## 3. Одиннадцать таблиц не прочитаны на взаимоисключительность
`LANGUAGE.md` объявил, что строки таблицы решений взаимоисключающи по
умолчанию, а иной порядок объявляется явно. Объявление не делает таблицы
@@ -76,7 +60,7 @@ BCP 14 и списки эквивалентных словесных форм IS
Работа читательская, машине не даётся; в список проверок она уже записана в
разделе «Чтением, потому что машине не даётся».
## 5. Описание языка отдельно от набора конвенций
## 4. Описание языка отдельно от набора конвенций
`LANGUAGE.md` и `GUIDE.md` описывают, **как** пишутся конвенции;
`conventions/`**один конкретный** набор. Сейчас они склеены в одном
@@ -101,7 +85,7 @@ BCP 14 и списки эквивалентных словесных форм IS
# Канон, тулинг, подключение
## 6. Тулинг: две разные задачи в одном `conv`
## 5. Тулинг: две разные задачи в одном `conv`
Сейчас в `conv` смешаны две категории работы, и они расходятся по всему —
по частоте запуска, по тому, кто запускает, и по тому, что считается
@@ -116,7 +100,8 @@ BCP 14 и списки эквивалентных словесных форм IS
**Установка в проект.** Манифест `.conventions.toml`, сборка файла темы из
слоёв (`arch` → язык → стек), сохранение при пересборке всего, что ниже
маркера, предупреждение о висячих ссылках на неподписанные темы. Запускается
маркера, `READING.md` рядом с копиями, предупреждение о висячих ссылках на
неподписанные темы. Запускается
в репозитории-потребителе, изредка, провал — это чаще «посмотри глазами»,
чем «ошибка». Отчёта «канон ушёл вперёд» здесь нет: его делает `git diff`
после пересборки.
@@ -132,7 +117,7 @@ BCP 14 и списки эквивалентных словесных форм IS
ссылках: это установка, а не целостность, но список подписок ему нужен из
манифеста.
Часть проверок из этого списка сейчас нереализуема по причине из вопроса 2,
Часть проверок из этого списка сейчас нереализуема по причине из вопроса 1,
так что порядок такой: сначала язык, потом чекер.
Перед тем как переписывать, стоит посмотреть на два готовых прототипа:
@@ -140,7 +125,7 @@ BCP 14 и списки эквивалентных словесных форм IS
манифеста и `vendir.yml` — как пример того, где проходит граница между «чего
хочу» и «что получил».
## 7. Пары слоёв и темы без базы
## 6. Пары слоёв и темы без базы
Отложено сознательно, но список стоит держать перед глазами:
@@ -161,7 +146,7 @@ BCP 14 и списки эквивалентных словесных форм IS
- Вынос арх-ядра из `errors` и `logging` закроет две хрупкие ссылки из
`web-ui` (стек) в go-слой — единственные ссылки стек → язык в каноне.
## 8. Подключение к репозиториям
## 7. Подключение к репозиториям
Ничего ещё не подключено. Кандидаты — jellybit и pet-project-server.
Понадобится: заполнить локальную часть копий тем, что сейчас в этих
@@ -170,7 +155,7 @@ BCP 14 и списки эквивалентных словесных форм IS
строка в `AGENTS.md` каждого потребителя про то, что файлы в
`docs/conventions/` — копии.
## 9. Тулинг на Go, живущий независимо
## 8. Тулинг на Go, живущий независимо
Сейчас `conv` — питоновский скрипт внутри канона, то есть тулинг и данные в
одном репозитории и правятся одним движением. Мысль: вынести в отдельный
@@ -179,10 +164,10 @@ Go-бинарь со своим релизным циклом, ставить ч
Что за этим стоит помимо вкуса: независимый бинарь физически не даёт править
инструмент «заодно» с правкой конвенции, работает против **любого** канона и
любого потребителя — что прямо требуется вопросом 5, — и снимает питон из
любого потребителя — что прямо требуется вопросом 4, — и снимает питон из
зависимостей репозиториев-потребителей.
Порядок обратный ожидаемому: пока вопрос 5 не сделан, инструмент всё равно
Порядок обратный ожидаемому: пока вопрос 4 не сделан, инструмент всё равно
работает против одного конкретного канона, и независимый релизный цикл ему
нечего обслуживать. Сначала 5, потом 9. Разделение из вопроса 6 при этом
нечего обслуживать. Сначала 4, потом 8. Разделение из вопроса 5 при этом
дешевле заложить сразу, чем отпиливать потом.