manifest.toml переименован в suite.toml
- родовое «манифест» заменено именем уровня: файл в наборе описывает сам набор, файл в проекте — подключённые конвенции, и каждый назван по тому, что описывает - по имени рядом лежащего манифеста определяется контекст: suite.toml — набор, .conventions.toml — проект; в TOOL.md решение зафиксировано, из открытых вопросов убрано
This commit is contained in:
@@ -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]`
|
||||||
|
|||||||
@@ -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` | в проекте | подключение: откуда копии, какие темы, язык, стек |
|
||||||
|
|
||||||
Манифест набора — единственное место, где перечислены оба идентификатора
|
Манифест набора — единственное место, где перечислены оба идентификатора
|
||||||
|
|||||||
@@ -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` — как пример границы между «чего хочу» и «что получил».
|
||||||
|
|||||||
@@ -1,11 +1,13 @@
|
|||||||
# Манифест набора конвенций.
|
# suite.toml — манифест набора конвенций.
|
||||||
#
|
#
|
||||||
# Манифестов в модели два, и они отвечают на разные вопросы:
|
# Манифестов в модели два, и каждый назван по тому, что описывает:
|
||||||
#
|
#
|
||||||
# - этот, в наборе, описывает сам набор: какие в нём темы и какие префиксы
|
# - `suite.toml` здесь, в наборе, — сам набор: язык записи, темы, занятые
|
||||||
# правил заняты;
|
# префиксы правил;
|
||||||
# - `.conventions.toml` в репозитории-потребителе описывает подключение:
|
# - `.conventions.toml` в проекте — подключение: откуда взяты копии, какие
|
||||||
# откуда взяты копии, какие темы выбраны, какие язык и стек.
|
# темы выбраны, какие язык и стек.
|
||||||
|
#
|
||||||
|
# По тому, какой из двух лежит рядом, видно, где ты находишься.
|
||||||
#
|
#
|
||||||
# Оба идентификатора набора — тема и префикс — живут здесь, потому что
|
# Оба идентификатора набора — тема и префикс — живут здесь, потому что
|
||||||
# правила у них общие: объявляются в шапке файла, сверяются с манифестом,
|
# правила у них общие: объявляются в шапке файла, сверяются с манифестом,
|
||||||
Reference in New Issue
Block a user