diff --git a/TODO.md b/TODO.md index af14bb9..2e78895 100644 --- a/TODO.md +++ b/TODO.md @@ -23,7 +23,25 @@ Работа читательская, машине не даётся; в список проверок она уже записана в разделе «Чтением, потому что машине не даётся». -## 2. Описание языка отдельно от набора конвенций +## 2. Шесть сниппетов сидят в блоке нормы + +С появлением блока ПРИМЕРЫ у кода в правиле есть своё место, но шесть правил +несут сниппет **внутри блока нормы** — там, где он по границе правила читается +как «требуется ровно такой код»: GCFG-7, GCFG-9, SLOG-20, GTIM-8, HTMX-7, +HTMX-24. Кода внутри обоснований в каноне нет ни одного, так что разбирать +нужно только эти шесть. + +Разбор по одному, вердикт из двух: сниппет — часть требования или иллюстрация +к нему. У GTIM-8 (`ReplaceAttr` с приведением к UTC) это похоже на норму: там +важна конкретная точка вмешательства. У HTMX-7 и SLOG-20 — скорее иллюстрация +формы вызова, и ей место в ПРИМЕРЫ. + +Цена ошибки в обе стороны понятна. Оставленный в норме пример превращает +деталь кода в требование, которое никто не имел в виду, и устаревает вместе с +API, а норму при этом нельзя поправить, не задев требование. Унесённая в +ПРИМЕРЫ норма, наоборот, перестаёт быть обязательной — блок иллюстративный. + +## 3. Описание языка отдельно от набора конвенций `LANGUAGE.md` и `GUIDE.md` описывают, **как** пишутся конвенции; `conventions/` — **один конкретный** набор. Сейчас они склеены в одном @@ -48,7 +66,7 @@ # Канон, тулинг, подключение -## 3. Тулинг: две разные задачи в одном `conv` +## 4. Тулинг: две разные задачи в одном `conv` Сейчас в `conv` смешаны две категории работы, и они расходятся по всему — по частоте запуска, по тому, кто запускает, и по тому, что считается @@ -89,7 +107,7 @@ манифеста и `vendir.yml` — как пример того, где проходит граница между «чего хочу» и «что получил». -## 4. Пары слоёв и темы без базы +## 5. Пары слоёв и темы без базы Отложено сознательно, но список стоит держать перед глазами: @@ -110,7 +128,7 @@ - Вынос арх-ядра из `errors` и `logging` закроет две хрупкие ссылки из `web-ui` (стек) в go-слой — единственные ссылки стек → язык в каноне. -## 5. Подключение к репозиториям +## 6. Подключение к репозиториям Ничего ещё не подключено. Кандидаты — jellybit и pet-project-server. Понадобится: заполнить локальную часть копий тем, что сейчас в этих @@ -119,7 +137,7 @@ строка в `AGENTS.md` каждого потребителя про то, что файлы в `docs/conventions/` — копии. -## 6. Тулинг на Go, живущий независимо +## 7. Тулинг на Go, живущий независимо Сейчас `conv` — питоновский скрипт внутри канона, то есть тулинг и данные в одном репозитории и правятся одним движением. Мысль: вынести в отдельный @@ -128,10 +146,10 @@ Go-бинарь со своим релизным циклом, ставить ч Что за этим стоит помимо вкуса: независимый бинарь физически не даёт править инструмент «заодно» с правкой конвенции, работает против **любого** канона и -любого потребителя — что прямо требуется вопросом 2, — и снимает питон из +любого потребителя — что прямо требуется вопросом 3, — и снимает питон из зависимостей репозиториев-потребителей. -Порядок обратный ожидаемому: пока вопрос 2 не сделан, инструмент всё равно +Порядок обратный ожидаемому: пока вопрос 3 не сделан, инструмент всё равно работает против одного конкретного канона, и независимый релизный цикл ему -нечего обслуживать. Сначала 2, потом 6. Разделение из вопроса 3 при этом +нечего обслуживать. Сначала 3, потом 7. Разделение из вопроса 4 при этом дешевле заложить сразу, чем отпиливать потом.