язык записи опёрт на стандарты, словарь стал параметром
- шкала обязательности объявлена инвариантом, а набор ключевых слов — параметром естественного языка набора: для английского готовый словарь даёт BCP 14, для прочих берут перевод стандарта или делают свой; отклонены синонимы ступеней и `SHALL`, занятый OpenSpec - применены шесть дельт: нормативно только заглавное написание (RFC 8174), ДОЛЖЕН требует названного вреда и машинной проверки сразу, ДОПУСКАЕТСЯ адресовано рецензенту, МЕХАНИЗИРОВАНО выведено из шкалы в отметку рядом с модальностью (ISO/IEC/IEEE 29148), у таблиц объявлены политика совпадения и полнота (DMN) - «Форма записи — LANGUAGE.md» в двенадцати конвенциях заменена строкой о версии языка по образцу boilerplate BCP 14: пути канона в копии не существует, а словарь и правило заглавных строка несёт сама
This commit is contained in:
@@ -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 уже
|
||||
говорит «чужой темы», и второе правило про то же место придётся держать
|
||||
согласованным с первым.
|
||||
|
||||
## Из вчерашнего, не закрыто
|
||||
|
||||
|
||||
Reference in New Issue
Block a user