manifest.toml переименован в suite.toml

- родовое «манифест» заменено именем уровня: файл в наборе описывает сам
  набор, файл в проекте — подключённые конвенции, и каждый назван по тому,
  что описывает
- по имени рядом лежащего манифеста определяется контекст: suite.toml —
  набор, .conventions.toml — проект; в TOOL.md решение зафиксировано, из
  открытых вопросов убрано
This commit is contained in:
av
2026-07-26 17:06:29 +03:00
parent e8fdc98557
commit b516bfb02c
4 changed files with 20 additions and 15 deletions
+2 -2
View File
@@ -9,7 +9,7 @@ code in this repository.
Канон конвенций разработки для личных проектов. Сами конвенции лежат в Канон конвенций разработки для личных проектов. Сами конвенции лежат в
`conventions/{arch,lang/<язык>,stack/<стек>}/`; обвязка канона (`README.md`, `conventions/{arch,lang/<язык>,stack/<стек>}/`; обвязка канона (`README.md`,
`LANGUAGE.md`, `GUIDE.md`, `READING.md`, `manifest.toml`, `conv`) живёт в `LANGUAGE.md`, `GUIDE.md`, `READING.md`, `suite.toml`, `conv`) живёт в
корне. К потребителю из неё едет только `READING.md` — короткое описание языка корне. К потребителю из неё едет только `READING.md` — короткое описание языка
для читателя копий. для читателя копий.
@@ -76,7 +76,7 @@ code in this repository.
латиницей, рекомендуется нижний kebab-case, годится любой идентификатор, латиницей, рекомендуется нижний kebab-case, годится любой идентификатор,
пригодный для имени файла. пригодный для имени файла.
- META-28: тема объявлена в шапке (`topic: time`) и стоит в манифесте набора - META-28: тема объявлена в шапке (`topic: time`) и стоит в манифесте набора
(`manifest.toml`, секция `[topics.live]`). Слои одной темы несут одно имя — (`suite.toml`, секция `[topics.live]`). Слои одной темы несут одно имя —
по нему собираются в один файл, как бы ни назывались их файлы; имя файла по нему собираются в один файл, как бы ни назывались их файлы; имя файла
повторяет тему из удобства. повторяет тему из удобства.
- META-29: имя темы не переиспользуется, снятое уходит в `[topics.retired]` - META-29: имя темы не переиспользуется, снятое уходит в `[topics.retired]`
+3 -3
View File
@@ -13,7 +13,7 @@
| [LANGUAGE.md](LANGUAGE.md) | язык записи правил: идентификаторы, модальность, обоснование | | [LANGUAGE.md](LANGUAGE.md) | язык записи правил: идентификаторы, модальность, обоснование |
| [GUIDE.md](GUIDE.md) | как ведут конвенции: когда заводить, механизация, отступления | | [GUIDE.md](GUIDE.md) | как ведут конвенции: когда заводить, механизация, отступления |
| [READING.md](READING.md) | как читать конвенцию: то, что едет к потребителю | | [READING.md](READING.md) | как читать конвенцию: то, что едет к потребителю |
| [manifest.toml](manifest.toml) | манифест набора: язык, темы, префиксы правил | | [suite.toml](suite.toml) | манифест набора: язык, темы, префиксы правил |
| `conv` | сборка копий | | `conv` | сборка копий |
К потребителю едет содержимое `conventions/` и один файл обвязки — К потребителю едет содержимое `conventions/` и один файл обвязки —
@@ -103,7 +103,7 @@ prefix: KEYS
документ, как бы ни назывались их файлы. Имя файла повторяет тему из документ, как бы ни назывались их файлы. Имя файла повторяет тему из
удобства, но истина — в шапке. удобства, но истина — в шапке.
Темы перечислены в манифесте набора — [`manifest.toml`](manifest.toml), Темы перечислены в манифесте набора — [`suite.toml`](suite.toml),
секция `[topics.live]`: имя и однострочное описание. Имя темы не секция `[topics.live]`: имя и однострочное описание. Имя темы не
переиспользуется по той же причине, что и префикс: оно живёт в чужих переиспользуется по той же причине, что и префикс: оно живёт в чужих
репозиториях — в шапке `origin:` каждой копии, в подписке манифеста, в тексте репозиториях — в шапке `origin:` каждой копии, в подписке манифеста, в тексте
@@ -229,7 +229,7 @@ MIGR-6 не соблюдается в `show_history`, `queue`: составны
| Файл | Где лежит | Что описывает | | Файл | Где лежит | Что описывает |
|---|---|---| |---|---|---|
| `manifest.toml` | в наборе | сам набор: темы и префиксы правил | | `suite.toml` | в наборе | сам набор: язык, темы, префиксы правил |
| `.conventions.toml` | в проекте | подключение: откуда копии, какие темы, язык, стек | | `.conventions.toml` | в проекте | подключение: откуда копии, какие темы, язык, стек |
Манифест набора — единственное место, где перечислены оба идентификатора Манифест набора — единственное место, где перечислены оба идентификатора
+7 -4
View File
@@ -38,6 +38,12 @@
формулировках употребляется «набор». «Потребитель» — слово про роль формулировках употребляется «набор». «Потребитель» — слово про роль
репозитория, а не про уровень. репозитория, а не про уровень.
Манифесты названы по тому, что описывают, а не по уровню ради симметрии:
`suite.toml` в наборе — идентичность набора, `.conventions.toml` в проекте —
подключённые конвенции. Точка в проекте отделяет служебное от содержимого
проекта; в наборе файл правится при каждой новой теме, и прятать его незачем.
Отсюда же бесплатное определение контекста: по имени рядом видно, где ты.
## Раскладка команд ## Раскладка команд
Глубина команды отражает частоту и адресата. Проектные команды выполняются в Глубина команды отражает частоту и адресата. Проектные команды выполняются в
@@ -62,7 +68,7 @@ convy suite new новая тема: шапка, префикс, запис
Три следствия для реализации: Три следствия для реализации:
- **контекст определяется и отказ говорится явно.** `.conventions.toml` рядом - **контекст определяется и отказ говорится явно.** `.conventions.toml` рядом
— проект, `manifest.toml` — набор. Проектная команда, набранная в наборе, не — проект, `suite.toml` — набор. Проектная команда, набранная в наборе, не
делает ничего наугад: она отказывает и подсказывает наборный аналог; делает ничего наугад: она отказывает и подсказывает наборный аналог;
- **помощь группируется заголовками** «В проекте» и «В наборе»: в плоском - **помощь группируется заголовками** «В проекте» и «В наборе»: в плоском
списке уровни не видны; списке уровни не видны;
@@ -152,9 +158,6 @@ convy suite new новая тема: шапка, префикс, запис
а не целостность, но список подписок ему нужен из манифеста подключения. а не целостность, но список подписок ему нужен из манифеста подключения.
- **Проверка на `convey`** в текстах — вместе с остальными проверками формы - **Проверка на `convey`** в текстах — вместе с остальными проверками формы
или отдельной мелочью. или отдельной мелочью.
- **Имена манифестов.** `suite.toml` в наборе против `.conventions.toml` в
проекте — каждый файл называет свой уровень. Сейчас `manifest.toml`;
решение вкусовое, но принимать его до первого потребителя дешевле.
- **Прототипы, на которые стоит посмотреть** до того, как писать: дистрибуция - **Прототипы, на которые стоит посмотреть** до того, как писать: дистрибуция
пакетов Vale (`.vale.ini``vale sync``styles/`) как образец манифеста и пакетов Vale (`.vale.ini``vale sync``styles/`) как образец манифеста и
`vendir.yml` — как пример границы между «чего хочу» и «что получил». `vendir.yml` — как пример границы между «чего хочу» и «что получил».
+8 -6
View File
@@ -1,11 +1,13 @@
# Манифест набора конвенций. # suite.toml — манифест набора конвенций.
# #
# Манифестов в модели два, и они отвечают на разные вопросы: # Манифестов в модели два, и каждый назван по тому, что описывает:
# #
# - этот, в наборе, описывает сам набор: какие в нём темы и какие префиксы # - `suite.toml` здесь, в наборе, сам набор: язык записи, темы, занятые
# правил заняты; # префиксы правил;
# - `.conventions.toml` в репозитории-потребителе описывает подключение: # - `.conventions.toml` в проекте — подключение: откуда взяты копии, какие
# откуда взяты копии, какие темы выбраны, какие язык и стек. # темы выбраны, какие язык и стек.
#
# По тому, какой из двух лежит рядом, видно, где ты находишься.
# #
# Оба идентификатора набора — тема и префикс — живут здесь, потому что # Оба идентификатора набора — тема и префикс — живут здесь, потому что
# правила у них общие: объявляются в шапке файла, сверяются с манифестом, # правила у них общие: объявляются в шапке файла, сверяются с манифестом,