язык: короткое описание для читателя копии едет в репозиторий
- заведён READING.md: словарь со значениями, форма правила и её граница, ссылки, локальная часть — без разделов о ведении набора и без META-ссылок, примеры на X-префиксах - сборщик кладёт его в docs/conventions/ и перезаписывает целиком; в манифест набора добавлена секция [language] с версией и двумя документами - META-30: правка словаря или состава частей правила доходит до READING.md, иначе потребитель толкует ДОПУСКАЕТСЯ по прежней версии
This commit is contained in:
@@ -12,13 +12,15 @@
|
||||
| `README.md` | устройство канона, оси, сборка копий, жизненный цикл |
|
||||
| [LANGUAGE.md](LANGUAGE.md) | язык записи правил: идентификаторы, модальность, обоснование |
|
||||
| [GUIDE.md](GUIDE.md) | как ведут конвенции: когда заводить, механизация, отступления |
|
||||
| [manifest.toml](manifest.toml) | манифест набора: темы и префиксы правил |
|
||||
| [READING.md](READING.md) | как читать конвенцию: то, что едет к потребителю |
|
||||
| [manifest.toml](manifest.toml) | манифест набора: язык, темы, префиксы правил |
|
||||
| `conv` | сборка копий |
|
||||
|
||||
Обвязка живёт только в каноне и в репозитории не оказывается — в копию едет
|
||||
лишь содержимое `conventions/`. Самодостаточность копии это не нарушает:
|
||||
конвенция называет язык записи одной строкой с номером версии и не ссылается
|
||||
на путь (`LANGUAGE.md`, раздел «Ссылка на язык из конвенции»).
|
||||
К потребителю едет содержимое `conventions/` и один файл обвязки —
|
||||
`READING.md`; остальная обвязка остаётся в каноне. Самодостаточность копии это
|
||||
не нарушает: конвенция называет язык записи одной
|
||||
строкой с номером версии и не ссылается на путь (`LANGUAGE.md`, раздел «Ссылка
|
||||
на язык из конвенции»).
|
||||
|
||||
Правило то же, что у ролей: **деплоится и читается только то, что лежит в
|
||||
git репозитория**. Канон никем не подключается на лету.
|
||||
@@ -151,6 +153,7 @@ extends: arch/db-identifiers.md
|
||||
```
|
||||
docs/conventions/
|
||||
README.md собственный, не собирается
|
||||
READING.md как читать конвенцию — приезжает из канона
|
||||
time.md arch/time.md + lang/go/time.md
|
||||
db-identifiers.md arch/db-identifiers.md + lang/go/db-identifiers.md
|
||||
app-directories.md arch/… + stack/ansible/…
|
||||
@@ -159,6 +162,10 @@ docs/conventions/
|
||||
Так конвенция остаётся самодостаточным документом: тот, кто проверяет по ней
|
||||
код — человек или агент, — читает один файл и не собирает тему из трёх мест.
|
||||
|
||||
Имена в директории делятся на три вида: `README.md` принадлежит репозиторию и
|
||||
сборщик его не трогает, `READING.md` принадлежит канону и перезаписывается
|
||||
целиком, остальные файлы — копии тем с шапкой `origin:` и локальной частью.
|
||||
|
||||
**Шапка копии** ставится при сборке и в каноне не хранится:
|
||||
|
||||
```yaml
|
||||
@@ -198,6 +205,24 @@ MIGR-6 не соблюдается в `show_history`, `queue`: составны
|
||||
репозитория. Файл, оставивший шапку, при следующем обновлении потеряет
|
||||
всё, что выше маркера.
|
||||
|
||||
## Язык записи едет вместе с копиями
|
||||
|
||||
Конвенция называет язык одной строкой с номером версии и без пути — строка
|
||||
работает и сама по себе. Но семантика заглавных слов живёт в описании языка, а
|
||||
описание в репозиторий-потребитель раньше не попадало: агент, читающий копию,
|
||||
принимал ДОПУСКАЕТСЯ за бытовое «можно» и терял ровно то, ради чего слово
|
||||
введено.
|
||||
|
||||
Поэтому в `docs/conventions/` сборщик кладёт `READING.md` — короткое описание
|
||||
для читателя правил: словарь со значениями, правило заглавных, из чего состоит
|
||||
правило и где его граница, как ссылаться, что живёт ниже маркера. Полное
|
||||
[LANGUAGE.md](LANGUAGE.md) остаётся в каноне: три его раздела адресованы
|
||||
автору набора и ссылаются на правила `GUIDE.md`, которых у потребителя нет.
|
||||
|
||||
Два документа — один словарь, и это единственное место, где возможен дрейф.
|
||||
Правка ключевых слов или состава частей правила обязана дойти до `READING.md`
|
||||
(META-30), а сверить их дёшево: таблицы либо совпадают, либо нет.
|
||||
|
||||
## Два манифеста
|
||||
|
||||
Манифестов в модели два, и они отвечают на разные вопросы:
|
||||
@@ -251,6 +276,7 @@ topics = ["time", "config", "db-identifiers"]
|
||||
conv list # какие темы есть в каноне
|
||||
conv add time # добавить тему в манифест и собрать файл
|
||||
conv pull # пересобрать всё, что перечислено в манифесте
|
||||
# (и обновить READING.md рядом с копиями)
|
||||
```
|
||||
|
||||
Отчёт о том, что изменилось, отдельной командой не выдаётся: после `pull`
|
||||
@@ -288,6 +314,7 @@ conv pull # пересобрать всё, что переч
|
||||
Модель выше — согласованная, а не реализованная. `conv` пока собран под
|
||||
прежнюю: зеркальное дерево копий вместо плоского, именованные регионы
|
||||
`<!-- local:имя -->` вместо одного маркера, `origin_hash` в шапке и команды
|
||||
`status`, `diff`, `push`. Сами конвенции уже приведены к новой модели —
|
||||
именованных регионов в каноне нет. Ни один репозиторий-потребитель не
|
||||
`status`, `diff`, `push`; `READING.md` рядом с копиями он тоже пока не
|
||||
кладёт. Сами конвенции уже приведены к новой модели — именованных регионов в
|
||||
каноне нет. Ни один репозиторий-потребитель не
|
||||
подключён, поэтому переход никого не ломает.
|
||||
|
||||
Reference in New Issue
Block a user