todo: закрыт вопрос про модель сборки, разобраны прототипы
- вопрос 3 закрыт: модель записана в README и GUIDE, отмечены три места, где итог разошёлся с прежними заготовками — нет лока, нет маркеров секций, локальные префиксы не объявляются, а резервируются буквой `X` - вопрос 4 переформулирован: регионы не переносятся в единую секцию, а удаляются из канона — наполнять их в каноне нечем - вопрос 7 заменён разбором: транспорт переизобретался, оси и сборка аналога не имеют, Vale отклонён; в 1, 9 и 10 добавлены следствия
This commit is contained in:
@@ -30,6 +30,13 @@ META-21 предлагает заменить путь на имя темы —
|
||||
где лежит полный документ. Самодостаточно и не тащит весь язык, но
|
||||
преамбула дублируется в каждом файле темы.
|
||||
|
||||
Появился четвёртый вариант, и он выглядит лучше трёх: **boilerplate-строка
|
||||
как в RFC 8174**. Каждая конвенция несёт одну фразу — «ключевые слова …
|
||||
толкуются как описано в „Языке конвенций“ версии 1 — тогда и только тогда,
|
||||
когда написаны заглавными». Пути нет, документа рядом нет, а норму исполнить
|
||||
можно: строка сама несёт и словарь, и правило капса. Разбирается в заходе
|
||||
про язык записи, вместе с версией — она же цепляет вопрос 9.
|
||||
|
||||
Сопутствующее: `GUIDE.md` в телах конвенций не упоминается ни разу —
|
||||
проверено, так что вопрос только про `LANGUAGE.md`.
|
||||
|
||||
@@ -63,46 +70,35 @@ META-21 предлагает заменить путь на имя темы —
|
||||
ссылках: это установка, а не целостность, но список подписок ему нужен из
|
||||
манифеста.
|
||||
|
||||
## 3. Согласованная модель сборки нигде не записана
|
||||
## 3. Модель сборки — записана, закрыто
|
||||
|
||||
Самое срочное. Договорённости про плоскую раскладку живут только в
|
||||
переписке, а репозиторий описывает прежнюю модель — и противоречит новой в
|
||||
нескольких местах сразу.
|
||||
Записана в `README.md` (разделы «Копия в репозитории» и «Манифест») и в
|
||||
`GUIDE.md` (META-22, META-23). Плоская раскладка, файл на тему, один маркер
|
||||
`<!-- conv:local -->`, манифест из источника и списка тем, направление
|
||||
строго одностороннее.
|
||||
|
||||
Что решено, но не зафиксировано:
|
||||
Против прежних заготовок разошлось в трёх местах:
|
||||
|
||||
- копия плоская, файл на тему: `docs/conventions/config.md`, а не дерево
|
||||
`arch/` + `lang/`;
|
||||
- файл темы собирается из секций `arch → языки → стеки → local` с
|
||||
машиночитаемыми маркерами `<!-- conv:section … -->` и `<!-- conv:local -->`;
|
||||
- языки и стеки образуют разреженную матрицу; файл темы собирает её строку,
|
||||
многоязычная тема держит несколько языковых секций в одном файле;
|
||||
- выбор описывается манифестом `.conventions.toml` в корне
|
||||
репозитория-потребителя; путь к канону там **не** хранится;
|
||||
- направление строго одностороннее: канон → код. Правка канона делается
|
||||
руками в каноне, потом пересборка;
|
||||
- локальные префиксы правил репозитория объявляются в манифесте и не
|
||||
пересекаются с реестром канона.
|
||||
- **лока нет** — «что было в прошлый раз» знает git, копии закоммичены, и
|
||||
автоматического обновления не существует; заодно из шапки копии ушли
|
||||
`origin_hash` и `synced`, осталось одно `origin:`;
|
||||
- **маркеров секций нет** — раз обновление перезаписывает всё выше
|
||||
локального маркера, разметка слоёв тулингу не нужна; слои идут обычными
|
||||
заголовками;
|
||||
- **локальные префиксы не объявляются в манифесте** — за репозиториями
|
||||
зарезервирована буква `X`, столкновение невозможно по построению.
|
||||
|
||||
Что этому прямо противоречит в репозитории сейчас:
|
||||
Остаётся переписать `conv`: сейчас в нём зеркальное дерево, именованные
|
||||
регионы, `origin_hash` и команды `status`/`diff`/`push`. Это вопрос 2.
|
||||
|
||||
- `README.md` → «Раскладка в репозитории» показывает зеркальное дерево
|
||||
`docs/conventions/arch/db-identifiers.md`;
|
||||
- `README.md` → «Команды» и «Контракт с агентом» описывают `conv push` и
|
||||
`conv push --new` как штатный путь; при односторонней модели транспорт
|
||||
назад исчезает, остаётся только детект «копия правлена вне локальной
|
||||
секции»;
|
||||
- `conv` содержит `cmd_push` со всей обвязкой (`--new`, `--force`).
|
||||
## 4. Именованные регионы — удалить из канона
|
||||
|
||||
## 4. Именованные регионы → одна локальная секция
|
||||
Решение принято и записано: регионов нет, есть один маркер
|
||||
`<!-- conv:local -->`, который ставит сборщик в копии. Значит регионы не
|
||||
переносятся в единую секцию, а **удаляются**: в каноне их нечем наполнять,
|
||||
локальное принадлежит копии.
|
||||
|
||||
Решено заменить регионы `<!-- local:имя -->` на одну локальную секцию в
|
||||
конце собранного файла: отступление ссылается на идентификатор правила
|
||||
(`DIRS-5`), а не стоит рядом с ним. Это то, что делает
|
||||
сравнение копии с каноном одним хешем и выкидывает из `conv` перенос
|
||||
регионов по именам.
|
||||
|
||||
Сделать перенос ещё предстоит: в каноне сейчас **31 регион в 12 файлах**.
|
||||
Остаётся механическая работа — **31 регион в 12 файлах**:
|
||||
|
||||
```
|
||||
7 связано 7 отступления 7 механизировано
|
||||
@@ -110,9 +106,9 @@ META-21 предлагает заменить путь на имя темы —
|
||||
1 проверки / поля / модель-владельца / маппинг / границы
|
||||
```
|
||||
|
||||
Отдельно решить, что делать с `связано`: сейчас это репо-специфичная часть
|
||||
раздела «Связано» (META-17), и при единой локальной секции она переезжает
|
||||
туда же — надо проверить, что META-17 после этого не противоречит сам себе.
|
||||
Вопрос про `связано` снят: META-17 переписан, канонический раздел «Связано»
|
||||
остаётся в тексте и содержит только ссылки, верные у всех, а репо-специфичные
|
||||
уходят под маркер.
|
||||
|
||||
## 5. Пары слоёв и темы без базы
|
||||
|
||||
@@ -144,27 +140,40 @@ META-21 предлагает заменить путь на имя темы —
|
||||
в закоммиченном файле не годится — репозиторий перестаёт быть
|
||||
самодостаточным и получает хардкод путей. Пересекается с вопросом 1.
|
||||
|
||||
## 7. Не переизобретено ли это
|
||||
## 7. Не переизобретено ли это — разобрано
|
||||
|
||||
Проверить перед тем, как вкладываться в тулинг. Ближайшие кандидаты, куда
|
||||
смотреть:
|
||||
Проверка перед вложением в тулинг сделана. По слоям:
|
||||
|
||||
- **copier / cruft** — шаблон проекта с последующим `update`: ровно та же
|
||||
задача «стянуть обновление апстрима, не затерев локальные правки», с
|
||||
ответом через три-way merge вместо наших регионов. Стоит понять, почему у
|
||||
них merge, а у нас исключение из сравнения.
|
||||
- **vendir** — вендоринг чужого содержимого с лок-файлом; ближе к нашей
|
||||
модели «канон это лавка».
|
||||
- **Vale** — линтер прозы с правилами в файлах: значительная часть проверок
|
||||
целостности канона (модальные слова вне правил, запрещённые формулировки)
|
||||
выражается его языком.
|
||||
- **RFC 2119 / 8174** — канонический источник модальных слов; наш словарь
|
||||
фактически его перевод, полезно сверить границы значений.
|
||||
- **EARS** — шаблоны требований (ubiquitous / event-driven / state-driven);
|
||||
соседняя формализация того же, что мы решили таблицами.
|
||||
- **Наборы правил для агентов** — `AGENTS.md`, cursor rules, скиллы: задачу
|
||||
«раздать читаемые агентом договорённости по репозиториям» сейчас решают
|
||||
несколько продуктов, и там уже могли устояться форматы.
|
||||
- **Язык записи** — велосипед, но собранный из проверенных деталей: словарь
|
||||
совпадает с RFC 2119/8174 вплоть до правила «нормативен только капс»,
|
||||
обязательное «Почему» — дисциплина из requirements engineering (ISO/IEC/IEEE
|
||||
29148), стабильные идентификаторы — из semgrep/ESLint. Менять архитектуру
|
||||
нечего, остались шесть точечных дельт — отдельным заходом.
|
||||
- **Оси и сборка** — аналога не нашлось. Ближайшие соседи (каскад `extends`
|
||||
в ESLint, слои стилей Vale) дают праву слоя **отменять** базу; наш запрет
|
||||
строже, и это содержательная часть. Вкладываться сюда.
|
||||
- **Транспорт** — переизобретался, но задача у нас другая, чем у copier и
|
||||
cruft. У них трёхсторонний merge потому, что шаблон порождает код, который
|
||||
правят везде: расхождение неограниченно. У нас расхождение ограничено и
|
||||
живёт под маркером, поэтому исключение из перезаписи лучше merge —
|
||||
детерминированно и без конфликтных маркеров. Из vendir/cruft взят разбор
|
||||
«манифест против лока», из ansible `blockinfile` — идея размечать
|
||||
управляемый кусок, а не локальный. Лок при этом не взят: его роль играет
|
||||
git.
|
||||
- **Раздача агентам** — не наша задача, остаёмся на `AGENTS.md`/`CLAUDE.md`
|
||||
плюс скиллы.
|
||||
|
||||
**Vale отклонён.** Из восьми проверок в `LANGUAGE.md` он честно закрывает
|
||||
две-три (модальные слова вне правил, запрещённые формулировки); остальные
|
||||
пять структурные — «у каждого `### ПРЕФИКС-N` есть модальность и Почему»,
|
||||
«номера без дыр вниз», «префикс совпадает с реестром». Это разбор документа,
|
||||
а не проверка токенов в области. Ради двух-трёх проверок тянуть ещё один
|
||||
бинарь и директорию стилей при одном пользователе не стоит.
|
||||
|
||||
**Что стоит посмотреть перед переписыванием `conv`** (вопрос 2): дистрибуцию
|
||||
пакетов Vale (`.vale.ini` → `vale sync` → `styles/`) как готовый прототип
|
||||
манифеста, и `vendir.yml` — как пример того, где проходит граница между
|
||||
«чего хочу» и «что получил».
|
||||
|
||||
## 8. Мультиязычность ключевых слов
|
||||
|
||||
@@ -198,6 +207,13 @@ MUST/SHOULD плотнее, чем на ДОЛЖЕН/СЛЕДУЕТ. Проти
|
||||
Цена — ещё одна сущность и ещё одна синхронизация. Проверить, не выйдет ли
|
||||
лечение хуже болезни при одном пользователе.
|
||||
|
||||
Оценка выросла: у выноса появилась вторая, независимая причина. Boilerplate-
|
||||
строка из вопроса 1 обязана назвать язык **с версией** — иначе она врёт при
|
||||
первом же изменении словаря. Версия предполагает документ, у которого версия
|
||||
бывает, то есть отдельный от набора. Так IETF и решил ровно эту задачу:
|
||||
RFC 2119 — самостоятельный документ, на который спецификации ссылаются
|
||||
номером, а не путём.
|
||||
|
||||
## 10. Тулинг на Go, живущий независимо
|
||||
|
||||
Сейчас `conv` — питоновский скрипт внутри канона, то есть тулинг и данные в
|
||||
@@ -214,6 +230,10 @@ Go-бинарь со своим релизным циклом, ставить ч
|
||||
«целостность канона / установка в проект» дешевле заложить сразу, чем
|
||||
отпиливать потом.
|
||||
|
||||
Порядок при этом обратный написанному: пока вопрос 9 не сделан, инструмент
|
||||
всё равно работает против одного конкретного канона, и независимый релизный
|
||||
цикл ему нечего обслуживать. Сначала 9, потом 10.
|
||||
|
||||
## 11. Ссылки на родительский слой своей темы
|
||||
|
||||
Из `lang/` и `stack/` ссылаться на идентификаторы своего же арх-слоя
|
||||
|
||||
Reference in New Issue
Block a user