язык записи опёрт на стандарты, словарь стал параметром

- шкала обязательности объявлена инвариантом, а набор ключевых слов —
  параметром естественного языка набора: для английского готовый словарь
  даёт BCP 14, для прочих берут перевод стандарта или делают свой; отклонены
  синонимы ступеней и `SHALL`, занятый OpenSpec
- применены шесть дельт: нормативно только заглавное написание (RFC 8174),
  ДОЛЖЕН требует названного вреда и машинной проверки сразу, ДОПУСКАЕТСЯ
  адресовано рецензенту, МЕХАНИЗИРОВАНО выведено из шкалы в отметку рядом с
  модальностью (ISO/IEC/IEEE 29148), у таблиц объявлены политика совпадения
  и полнота (DMN)
- «Форма записи — LANGUAGE.md» в двенадцати конвенциях заменена строкой о
  версии языка по образцу boilerplate BCP 14: пути канона в копии не
  существует, а словарь и правило заглавных строка несёт сама
This commit is contained in:
av
2026-07-26 13:42:10 +03:00
parent fea0285619
commit 9318087248
16 changed files with 395 additions and 205 deletions
+52 -63
View File
@@ -3,42 +3,18 @@
Черновик для следующего разговора: вопросы и варианты, а не принятые
решения.
## 1. Ссылка на `LANGUAGE.md` не переживает сборку
## 1. Ссылка на язык — закрыто
Все двенадцать конвенций во вводной прозе пишут «Форма записи —
`LANGUAGE.md`». Обвязка в репозиторий не едет (`conv` синхронизирует только
`conventions/`), поэтому в собранной копии эта ссылка указывает в никуда.
Заменено boilerplate-строкой по образцу BCP 14: каждая конвенция называет
ключевые слова, версию языка и правило заглавных, но не путь. Строка стоит
отдельным абзацем после вводной прозы во всех двенадцати файлах, «Форма
записи — `LANGUAGE.md`» удалена. Точный текст — в `LANGUAGE.md`, раздел
«Ссылка на язык из конвенции».
Это тот же класс дефекта, который вчера закрыло META-21 для ссылок между
темами: путь, верный в каноне, молча умирает при сборке. Разница в том, что
META-21 предлагает заменить путь на имя темы — а здесь заменять не на что,
целевого документа в репозитории просто нет.
Варианты, которые видно сейчас:
- **Убрать упоминание из тел конвенций.** Язык записи — забота того, кто
пишет канон, а не того, кто читает конвенцию в своём репозитории. Читателю
достаточно самого текста: модальные слова и «Почему» самоописательны.
Дешевле всего, но копия теряет указание, по каким правилам её править.
- **Возить обвязку вместе с конвенциями.** Тогда `LANGUAGE.md` и, возможно,
`GUIDE.md` появляются в `docs/conventions/` как ещё одни синхронизируемые
файлы. Честно, но противоречит нынешнему разделению «канон — конвенции,
корень — обвязка» и добавляет в репозиторий текст, который агенту при
чтении конвенции не нужен.
- **Вкладывать короткую преамбулу в собранный файл.** Сборщик пишет в шапку
три-четыре строки: что такое модальное слово, что «Почему» обязательно,
где лежит полный документ. Самодостаточно и не тащит весь язык, но
преамбула дублируется в каждом файле темы.
Появился четвёртый вариант, и он выглядит лучше трёх: **boilerplate-строка
как в RFC 8174**. Каждая конвенция несёт одну фразу — «ключевые слова …
толкуются как описано в „Языке конвенций“ версии 1 — тогда и только тогда,
когда написаны заглавными». Пути нет, документа рядом нет, а норму исполнить
можно: строка сама несёт и словарь, и правило капса. Разбирается в заходе
про язык записи, вместе с версией — она же цепляет вопрос 9.
Сопутствующее: `GUIDE.md` в телах конвенций не упоминается ни разу —
проверено, так что вопрос только про `LANGUAGE.md`.
Побочно: строка перечисляет модальные слова заглавными, то есть сама
нарушает проверку «заглавные модальные слова не встречаются вне правил».
Исключение записано в список проверок — так же, как оно устроено в BCP 14,
где boilerplate тоже содержит ключевые слова.
## 2. Тулинг: две разные задачи в одном `conv`
@@ -144,11 +120,12 @@ META-21 предлагает заменить путь на имя темы —
Проверка перед вложением в тулинг сделана. По слоям:
- **Язык записи** — велосипед, но собранный из проверенных деталей: словарь
совпадает с RFC 2119/8174 вплоть до правила «нормативен только капс»,
обязательное «Почему» — дисциплина из requirements engineering (ISO/IEC/IEEE
29148), стабильные идентификаторы — из semgrep/ESLint. Менять архитектуру
нечего, остались шесть точечных дельт — отдельным заходом.
- **Язык записи** — совпал со стандартами почти во всём: шкала и правило
«нормативно только заглавное» — BCP 14, обязательное обоснование и
единичность нормы — ISO/IEC/IEEE 29148, категории — ISO/IEC Directives
Part 2, таблицы решений — DMN, стабильные идентификаторы — semgrep/ESLint.
Шесть точечных дельт применены, опора на источники записана в `LANGUAGE.md`
разделом «Опора на стандарты».
- **Оси и сборка** — аналога не нашлось. Ближайшие соседи (каскад `extends`
в ESLint, слои стилей Vale) дают праву слоя **отменять** базу; наш запрет
строже, и это содержательная часть. Вкладываться сюда.
@@ -175,19 +152,28 @@ META-21 предлагает заменить путь на имя темы —
манифеста, и `vendir.yml` — как пример того, где проходит граница между
«чего хочу» и «что получил».
## 8. Мультиязычность ключевых слов
## 8. Мультиязычность ключевых слов — закрыто по механике
Модальные слова сейчас русские, и это осознанно: разный словарь держит
границу «конвенция — не спецификация» бесплатно. Вопрос — нужен ли
английский набор параллельно.
Вопрос был поставлен как «нужен ли английский набор параллельно русскому».
Ответ оказался другой формы: словарь — **параметр естественного языка
набора**, а не часть языка конвенций. Шкала из пяти ступеней инвариантна,
слова под неё подбираются: для английского готовый словарь даёт BCP 14, для
любого другого языка слова берут из перевода стандарта или переводят сами.
За: канон может однажды понадобиться на английском; агенты натренированы на
MUST/SHOULD плотнее, чем на ДОЛЖЕН/СЛЕДУЕТ. Против: два набора — это два
способа записать одно, и проверка «модальные слова не встречаются вне
правил» усложняется вдвое.
Отсюда следствия, снимающие исходный вопрос:
Если делать, то таблица ключевых слов должна принадлежать **описанию
языка**, а не каждой конвенции — то есть вопрос завязан на следующий.
- **параллельных наборов не бывает.** Словарь один на канон: два словаря
дают две формы записи одного требования и удваивают каждую проверку;
- **версия языка при смене словаря не меняется** — версия принадлежит шкале
и правилам формы, а не буквам. Прежняя оценка «английский набор = версия 2»
неверна;
- **`SHALL` не берётся ни в одном словаре**, потому что занято OpenSpec; для
английского это выбор в пользу `MUST` из BCP 14, а не `shall` из ISO;
- отметка о механизации стандартом не даётся ни в одном языке и подбирается
так же, как остальные слова (`МЕХАНИЗИРОВАНО` / `MECHANIZED`).
Открытым остаётся только прикладное: понадобится ли этому канону английская
версия вообще. Механика для неё уже описана, заводить заранее нечего.
## 9. Описание языка отдельно от набора конвенций
@@ -207,12 +193,14 @@ MUST/SHOULD плотнее, чем на ДОЛЖЕН/СЛЕДУЕТ. Проти
Цена — ещё одна сущность и ещё одна синхронизация. Проверить, не выйдет ли
лечение хуже болезни при одном пользователе.
Оценка выросла: у выноса появилась вторая, независимая причина. Boilerplate-
строка из вопроса 1 обязана назвать язык **с версией** — иначе она врёт при
первом же изменении словаря. Версия предполагает документ, у которого версия
бывает, то есть отдельный от набора. Так IETF и решил ровно эту задачу:
RFC 2119 — самостоятельный документ, на который спецификации ссылаются
номером, а не путём.
Срочность снята: версия появилась у `LANGUAGE.md` (ключ `version:` в шапке),
и boilerplate-строка из вопроса 1 уже ссылается на язык номером, а не путём —
не дожидаясь выноса. Отдельный репозиторий остаётся вопросом второго набора
конвенций, а не вопросом самодостаточности копии.
Что осталось поводом: из одного описания по-прежнему нельзя собрать второй
набор, и тулинг валидирует правила, зашитые в код, а не объявленную версию
языка. Оба повода включаются, только когда появится второй набор.
## 10. Тулинг на Go, живущий независимо
@@ -241,15 +229,16 @@ Go-бинарь со своим релизным циклом, ставить ч
никуда не ведёт — правило рядом. Ограничение META-20 писалось именно про
**чужую тему**, так что формально это уже разрешено.
Но стоит проговорить явно, потому что сейчас читается уже как запрет:
Формулировка проверки исправлена: в `LANGUAGE.md` теперь «префикс **чужой
темы** не встречается в абзаце с модальностью», и там же сказано, что
префикс своего базового слоя допустим. Ложного срабатывания на `GTIM`
`TIME-3` больше нет.
- в `LANGUAGE.md` проверка сформулирована как «**чужой префикс** не
встречается в абзаце с модальностью» — по букве это ловит и `GTIM`
`TIME-3`, то есть ложно срабатывает на ровно том случае, который
разрешён. Должно быть «префикс **чужой темы**»;
- обсудить, не добавить ли в META-20 явную строку **ДОПУСКАЕТСЯ** про
родительский слой: правило, которое читают как более строгое, чем оно
есть, заставляет авторов дублировать текст без нужды.
Осталось решить одно: добавлять ли в META-20 явную строку **ДОПУСКАЕТСЯ**
про родительский слой. За — правило, которое читают строже, чем оно есть,
заставляет авторов дублировать текст без нужды. Против — норма META-20 уже
говорит «чужой темы», и второе правило про то же место придётся держать
согласованным с первым.
## Из вчерашнего, не закрыто