From 67d51db212c9f5791be7ac6d7a8c61ec29467d47 Mon Sep 17 00:00:00 2001 From: Anton Vakhrushev Date: Sun, 26 Jul 2026 15:41:52 +0300 Subject: [PATCH] =?UTF-8?q?=D0=BC=D0=B5=D1=85=D0=B0=D0=BD=D0=B8=D0=B7?= =?UTF-8?q?=D0=B0=D1=86=D0=B8=D1=8F=20=D0=B1=D0=BE=D0=BB=D1=8C=D1=88=D0=B5?= =?UTF-8?q?=20=D0=BD=D0=B5=20=D1=80=D0=B0=D0=B7=D1=80=D0=B5=D1=88=D0=B0?= =?UTF-8?q?=D0=B5=D1=82=20=D1=83=D0=B4=D0=B0=D0=BB=D1=8F=D1=82=D1=8C=20?= =?UTF-8?q?=D0=BD=D0=BE=D1=80=D0=BC=D1=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - META-9 снят: удаление оставляло подписчика, пришедшего после, без нормы и без проверки, а «механизировано у всех» канону не проверить — списка подписчиков у него нет по построению - META-8 переписан в запрет: норма остаётся в правиле, чем бы её ни проверяли; линтер сообщает, что нарушено, но не что требуется (META-6) - МЕХАНИЗИРОВАНО объявлена свойством репозитория: в тексте конвенции отметки нет, её место — запись о механизации ниже маркера (META-7) --- CLAUDE.md | 9 +++++--- GUIDE.md | 51 ++++++++++++++++++------------------------ LANGUAGE.md | 64 ++++++++++++++++++++++++++++------------------------- README.md | 2 +- TODO.md | 46 ++++++++++++-------------------------- 5 files changed, 76 insertions(+), 96 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 719d127..765f306 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -37,8 +37,11 @@ code in this repository. до ДОЛЖЕН не повышает — иначе шкала наполняется проверяемыми мелочами. - ДОПУСКАЕТСЯ адресовано рецензенту: помеченный им выбор на ревью не обсуждается. -- **МЕХАНИЗИРОВАНО** — не модальность, а способ проверки: отметка стоит - рядом с модальным словом (`**ДОЛЖЕН. МЕХАНИЗИРОВАНО.**`), а не вместо него. +- **МЕХАНИЗИРОВАНО** — не модальность, а способ проверки, и свойство + репозитория, а не канона: в тексте конвенции отметки нет, она стоит при + записи о механизации в локальной части копии (META-7). +- META-8: норма не удаляется из канона никогда, чем бы её ни проверяли. + Механизация её не заменяет и не сокращает. - Метки правила — **ПОЧЕМУ** и **МЕХАНИЗИРОВАНО** — тоже словарь набора и перечислены в строке о версии языка наравне с модальными словами. - Заглавные модальные слова не употребляются вне правил: ни в «Область @@ -113,7 +116,7 @@ code in this repository. построению. META-27: машинная проверка желательна, но ступени не задаёт; проверяющий по умолчанию — читатель правила, человек или агент. - META-10: блок ПОЧЕМУ не удаляется никогда, в том числе после того, как - норма уехала в линтер. + правило стало проверяться линтером. - META-1: один файл — ровно один повторяющийся выбор. META-2: конвенция заводится, когда решение принимается третий раз. - Репозиторного в каноне нет вовсе: механизация, отступления и ссылки на код diff --git a/GUIDE.md b/GUIDE.md index 2147487..746dae6 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -112,9 +112,9 @@ prefix: META ### META-3. Новая конвенция пишется там, где заболело -**СЛЕДУЕТ.** Первые шаги пути «находка → конвенция → правило линтера → -удаление прозы» делаются в репозитории, где случилась находка; в канон -продвигается общая часть. +**СЛЕДУЕТ.** Первые шаги пути «находка → конвенция → правило линтера» +делаются в репозитории, где случилась находка; в канон продвигается общая +часть. **ПОЧЕМУ.** Правило, написанное сразу в общем виде, не проверено ни одним применением, и условие применимости у него придумано, а не найдено, — @@ -228,8 +228,9 @@ prefix: META **ПОЧЕМУ.** Линтер не забывает, ничего не стоит на каждом прогоне и краснеет до ревью, а не на нём: там, где проверка пишется, она дешевле самого -внимательного чтения, и путь «находка → конвенция → проверка → удаление -прозы» кончается ею (META-9). Условием ступени она при этом не является: +внимательного чтения, и путь «находка → конвенция → проверка» кончается ею. +Норму она при этом не заменяет и не отменяет (META-8). Условием ступени +механизация не является: проверяющий по умолчанию — читатель правила (META-6), а если требовать скрипт, весь канон стоит в СЛЕДУЕТ до того дня, когда скрипты появятся. Ступень говорит о важности нормы, а не о состоянии инструментов. @@ -245,36 +246,25 @@ prefix: META читатель догадывается сам, к какому утверждению относится проверка, — и догадывается по-разному. -### META-8. Формулировка не удаляется из канона, пока механизирована не у всех +### META-8. Норма из канона не удаляется, чем бы она ни проверялась -**НЕ ДОЛЖЕН.** Норма остаётся в каноне, пока хотя бы у одного потребителя -машинной проверки нет. +**НЕ ДОЛЖЕН.** Формулировка нормы остаётся в правиле независимо от того, кто и +чем её проверяет. -**ПОЧЕМУ.** У кого линтера нет, тот после удаления остаётся без правила -вообще: ни проверки, ни текста. Механизация у одного потребителя ничего не -говорит о прочих, поэтому удалять по факту «у нас уже проверяется» — -значит чинить свой файл за чужой счёт. - -Списка подписчиков канон по построению не знает, поэтому факт «механизировано -у всех» устанавливается обходом репозиториев вручную — это часть работы по -удалению нормы, а не то, что можно проверить машиной (см. `LANGUAGE.md`, -состояние МЕХАНИЗИРОВАНО). - -### META-9. Общая механизация разрешает удалить норму из канона - -**ДОПУСКАЕТСЯ.** Правило, уехавшее в общий конфиг линтера или в общую роль, -удаляется из канона. - -**ПОЧЕМУ.** Формулировка, дублирующая работающую у всех проверку, -размазывает внимание: файл на несколько сотен строк заставляет человека и -агента добросовестно вычитывать тривиальное именование и не доходить до -формы решения. Явное разрешение нужно, чтобы META-8 не читался как запрет -удалять вообще. +**ПОЧЕМУ.** Проверяющий по умолчанию — читатель правила (META-6), и удаление +нормы забирает у него ровно то, чем он проверяет: линтер сообщает, что +нарушено, но не сообщает, что требуется. Условие «механизировано у всех» +спасти не может: оно измеряется в день удаления, а подписчики появляются +после. Репозиторий, подключившийся через год, получил бы правило без нормы и +без проверки — заголовок с обоснованием и никакого способа узнать, что́ именно +предписано, кроме git-истории канона, до которой он не дойдёт. Списка +подписчиков у канона к тому же нет по построению, так что «у всех» ему всё +равно не проверить. ### META-10. Обоснование не удаляется никогда -**НЕ ДОЛЖЕН.** Блок ПОЧЕМУ остаётся и после того, как норма уехала в -линтер. +**НЕ ДОЛЖЕН.** Блок ПОЧЕМУ остаётся и после того, как правило стало +проверяться линтером. **ПОЧЕМУ.** Линтер сообщает, что нарушено, но не сообщает, зачем правило существует. Без обоснования не видно, когда причина отпала, — проверка @@ -397,3 +387,4 @@ prefix: META |---|---|---| | META-16 | имя файла — kebab-case | вреда от нарушения нет (META-25); осталось прозой в «Оформлении» | | META-26 | запрет слов обязательства в обосновании | правило о заглавных уже делает строчное слово ненормативным, а форму обоснования рамками не ограничивают | +| META-9 | общая механизация разрешала удалить норму из канона | снято 2026-07-26: удаление оставляло будущего подписчика без нормы и без проверки, а «механизировано у всех» канону не проверить (META-8) | diff --git a/LANGUAGE.md b/LANGUAGE.md index b4e81c7..4e766d7 100644 --- a/LANGUAGE.md +++ b/LANGUAGE.md @@ -69,8 +69,8 @@ version: 1 - **Отступления.** «У нас не так» бесполезно, пока не сказано, что именно «не так». Со ссылкой на правило отступления становятся счётными: видно, сколько правил конвенции репозиторий реально не соблюдает. -- **Промоут находки.** Путь «находка → конвенция → правило линтера → - удаление прозы» требует ручки, за которую берут конкретное правило. +- **Промоут находки.** Путь «находка → конвенция → правило линтера» требует + ручки, за которую берут конкретное правило. Общий знаменатель — **идентификатор**. Модальные слова и таблицы полезны, но вторичны. @@ -238,9 +238,10 @@ Directives, Part 2, по одной форме записи на ступень, | рекомендация против | НЕ СЛЕДУЕТ | SHOULD NOT | | разрешение | ДОПУСКАЕТСЯ | MAY | -**Метки правила.** Обязательности не задают, а размечают его части. -Стандартом не даются ни в одном языке: в BCP 14 таких понятий нет, слова -подбираются под язык так же, как остальные. +**Метки.** Обязательности не задают, а размечают: ПОЧЕМУ — часть правила, +МЕХАНИЗИРОВАНО — запись о проверке в копии. Стандартом не даются ни в одном +языке: в BCP 14 таких понятий нет, слова подбираются под язык так же, как +остальные. | Метка | Русский | Английский | |---|---|---| @@ -304,33 +305,35 @@ Directives, Part 2, по одной форме записи на ступень, инструментов. Линтер сильнее чтения — он не забывает, ничего не стоит на каждом прогоне и краснеет до ревью, — поэтому механизация желательна везде, где проверка пишется (META-27), и остаётся концом пути «находка → конвенция → -проверка → удаление прозы». Но обязательным условием высшей ступени она не -является: иначе весь канон стоял бы в СЛЕДУЕТ до появления скриптов, которых -пока нет ни одного. +проверка». Но обязательным условием высшей ступени она не является: иначе весь +канон стоял бы в СЛЕДУЕТ до появления скриптов, которых пока нет ни одного. -Когда правило механизировано у всех потребителей, его норма из канона -удаляется, а модальность и обоснование остаются: +**Механизация нормы не заменяет и не сокращает.** Норма остаётся в правиле +навсегда — как и обоснование (META-8, META-10), — сколько бы проверок её ни +подпирало. Причин три: + +- **линтер сообщает, что нарушено, но не сообщает, что требуется.** Без нормы + правило нечем исполнить и не с чем сверить вердикт проверки, а проверяющий + по умолчанию читает именно норму; +- **подписчики появляются позже.** Репозиторий, подключившийся через год, + получил бы правило без нормы и без линтера — ни текста, ни проверки; +- **«механизировано у всех» набору не проверить:** списка подписчиков у него + нет по построению. + +**Отметка — свойство репозитория, а не набора.** Механизирована норма или нет, +зависит от того, чей это репозиторий, поэтому в тексте конвенции отметки нет: +её место — запись о механизации в локальной части копии, со ссылкой на +идентификатор правила (META-7). ```markdown -### XMIG-6. Дефолтов времени в схеме БД нет + -**ДОЛЖЕН. МЕХАНИЗИРОВАНО.** Проверяется общим правилом линтера; -формулировка удалена, потому что дублировала работающую проверку. - -**ПОЧЕМУ.** Дефолт превращает забытую вставку в тихо работающий код… +XMIG-2, XMIG-4 — МЕХАНИЗИРОВАНО: `internal/archrules`, в новых миграциях. ``` -- Идентификатор и заголовок сохраняются: ссылки из репозиториев продолжают - указывать на то же утверждение. -- Модальность сохраняется, поэтому «все ли ДОЛЖЕН механизированы» - остаётся вычислимым вопросом, а не предметом чтения всего канона. -- Обоснование остаётся навсегда — линтер сообщает, что нарушено, но не - сообщает, зачем правило существует, и без обоснования нельзя понять, - когда проверку пора отменять. - -Факт «механизировано у всех» устанавливается вручную: канон по построению -не знает списка подписчиков, и обойти репозитории перед удалением нормы — -часть работы, а не то, что можно проверить автоматически. +Так у правила остаются оба атрибута сразу: обязательность — в норме, которая +приезжает из набора и одинакова у всех, способ проверки — в записи, которая +принадлежит репозиторию и у каждого своя. ## Таблицы решений @@ -459,8 +462,7 @@ Directives, Part 2, по одной форме записи на ступень, ```markdown -XMIG-2, XMIG-4 механизированы — `internal/archrules` (проверяются в новых -миграциях). +XMIG-2, XMIG-4 — МЕХАНИЗИРОВАНО: `internal/archrules`, в новых миграциях. XMIG-6 не соблюдается в легаси-таблицах `show_history`, `queue`: составные ключи там появились до конвенции, переписывание требует миграции данных. @@ -489,8 +491,8 @@ XMIG-6 не соблюдается в легаси-таблицах `show_histor - заголовки правил файла используют только его собственный префикс; - номера уникальны внутри файла и не имеют пропусков вниз (новое правило берёт следующий свободный, а не первый освободившийся); -- у каждого `### <ПРЕФИКС>-` есть модальное слово и блок ПОЧЕМУ; - отметка МЕХАНИЗИРОВАНО стоит рядом с модальностью, а не вместо неё; +- у каждого `### <ПРЕФИКС>-` есть модальное слово, норма и блок ПОЧЕМУ: + ни норма, ни обоснование не удаляются никогда (META-8, META-10); - вводная проза содержит строку о версии языка; - ссылки вида `<ПРЕФИКС>-` — хоть в тексте канона, хоть в локальной части копии — указывают на правила, которые ещё существуют; @@ -509,6 +511,8 @@ XMIG-6 не соблюдается в легаси-таблицах `show_histor - имя темы, названное в ссылке или в подписке потребителя, тоже разрешается по манифесту: ссылка на снятую тему не проходит молча; - префиксы локальных правил копии начинаются на `X`; +- отметки МЕХАНИЗИРОВАНО в тексте конвенции нет: её место — запись о + механизации в локальной части копии (META-7); - префикс **чужой темы** не встречается в абзаце с модальностью (META-20); префикс арх-слоя своей темы там допустим (META-24), префикс другого языка или стека — нет; diff --git a/README.md b/README.md index 6f347d2..76a08ab 100644 --- a/README.md +++ b/README.md @@ -179,7 +179,7 @@ origin: time ```markdown -MIGR-2, MIGR-4 механизированы — `internal/archrules`. +MIGR-2, MIGR-4 — МЕХАНИЗИРОВАНО: `internal/archrules`. MIGR-6 не соблюдается в `show_history`, `queue`: составные ключи там появились до конвенции, миграция данных не окупается. ``` diff --git a/TODO.md b/TODO.md index aca1f14..1da70f5 100644 --- a/TODO.md +++ b/TODO.md @@ -4,30 +4,12 @@ решения. Закрытый вопрос отсюда удаляется — принятое решение живёт в `README.md`, `GUIDE.md` или `LANGUAGE.md`, а не в этом файле. -Две секции: сначала язык и подход, потом канон с тулингом. Пункты 1–4 +Две секции: сначала язык и подход, потом канон с тулингом. Пункты 1–3 пришли из внешнего ревью описания языка и проверены по файлам на месте. # Язык и подход -## 1. МЕХАНИЗИРОВАНО не переживает нового подписчика - -META-8 запрещает удалять норму, пока механизирована не у всех, и защищает -тем самым потребителей, существующих **на момент удаления**. Будущих не -защищает никто. - -Сценарий: норма удалена, потому что у всех трёх тогдашних потребителей был -линтер. Через год подключается четвёртый репозиторий, подписывается на тему — -и получает правило без формулировки и без проверки: ни текста, ни линтера, -восстановление только через git-историю канона. - -Смежное: «общий конфиг линтера или общая роль» из META-9 — сущность, которой -в модели распространения (манифест, темы, слои) не существует, и непонятно, -как она доезжает до потребителя. И отдельно: запись «проверяется общим -правилом линтера» — это утверждение о состоянии инфраструктуры потребителей -в тексте канона, то есть ровно то, что запрещает META-4. Либо это законное -исключение, и тогда его надо назвать, либо конфликт. - -## 2. Семантика ключевых слов в копию не едет +## 1. Семантика ключевых слов в копию не едет Строка о версии языка перечисляет слова, но не их значения, а всё нетривиальное в шкале живёт только в `LANGUAGE.md`, который в репозиторий не @@ -43,7 +25,7 @@ META-8 запрещает удалять норму, пока механизир копиями короткую выжимку семантики; расширить строку о версии до двух-трёх предложений; или признать ограничение и записать его явно. -## 3. Две «механические» проверки без источника данных +## 2. Две «механические» проверки без источника данных В списке «разбором текста» стоят два пункта, которые без дополнительного реестра нерешаемы: @@ -60,7 +42,7 @@ META-8 запрещает удалять норму, пока механизир требуют, а манифест набора хранит только темы и префиксы. Пока реестр снятых номеров не объявлен частью языка, оба пункта принадлежат списку «чтением». -## 4. Натяжки в опоре на стандарты +## 3. Натяжки в опоре на стандарты Три места, где источнику приписано чуть больше, чем в нём есть: @@ -79,7 +61,7 @@ META-8 запрещает удалять норму, пока механизир Остальное в таблице проверку выдержало, включая вторую половину `MAY` из BCP 14 и списки эквивалентных словесных форм ISO Directives. -## 5. Одиннадцать таблиц не прочитаны на взаимоисключительность +## 4. Одиннадцать таблиц не прочитаны на взаимоисключительность `LANGUAGE.md` объявил, что строки таблицы решений взаимоисключающи по умолчанию, а иной порядок объявляется явно. Объявление не делает таблицы @@ -94,7 +76,7 @@ BCP 14 и списки эквивалентных словесных форм IS Работа читательская, машине не даётся; в список проверок она уже записана в разделе «Чтением, потому что машине не даётся». -## 6. Описание языка отдельно от набора конвенций +## 5. Описание языка отдельно от набора конвенций `LANGUAGE.md` и `GUIDE.md` описывают, **как** пишутся конвенции; `conventions/` — **один конкретный** набор. Сейчас они склеены в одном @@ -119,7 +101,7 @@ BCP 14 и списки эквивалентных словесных форм IS # Канон, тулинг, подключение -## 7. Тулинг: две разные задачи в одном `conv` +## 6. Тулинг: две разные задачи в одном `conv` Сейчас в `conv` смешаны две категории работы, и они расходятся по всему — по частоте запуска, по тому, кто запускает, и по тому, что считается @@ -150,7 +132,7 @@ BCP 14 и списки эквивалентных словесных форм IS ссылках: это установка, а не целостность, но список подписок ему нужен из манифеста. -Часть проверок из этого списка сейчас нереализуема по причине из вопроса 3, +Часть проверок из этого списка сейчас нереализуема по причине из вопроса 2, так что порядок такой: сначала язык, потом чекер. Перед тем как переписывать, стоит посмотреть на два готовых прототипа: @@ -158,7 +140,7 @@ BCP 14 и списки эквивалентных словесных форм IS манифеста и `vendir.yml` — как пример того, где проходит граница между «чего хочу» и «что получил». -## 8. Пары слоёв и темы без базы +## 7. Пары слоёв и темы без базы Отложено сознательно, но список стоит держать перед глазами: @@ -179,7 +161,7 @@ BCP 14 и списки эквивалентных словесных форм IS - Вынос арх-ядра из `errors` и `logging` закроет две хрупкие ссылки из `web-ui` (стек) в go-слой — единственные ссылки стек → язык в каноне. -## 9. Подключение к репозиториям +## 8. Подключение к репозиториям Ничего ещё не подключено. Кандидаты — jellybit и pet-project-server. Понадобится: заполнить локальную часть копий тем, что сейчас в этих @@ -188,7 +170,7 @@ BCP 14 и списки эквивалентных словесных форм IS строка в `AGENTS.md` каждого потребителя про то, что файлы в `docs/conventions/` — копии. -## 10. Тулинг на Go, живущий независимо +## 9. Тулинг на Go, живущий независимо Сейчас `conv` — питоновский скрипт внутри канона, то есть тулинг и данные в одном репозитории и правятся одним движением. Мысль: вынести в отдельный @@ -197,10 +179,10 @@ Go-бинарь со своим релизным циклом, ставить ч Что за этим стоит помимо вкуса: независимый бинарь физически не даёт править инструмент «заодно» с правкой конвенции, работает против **любого** канона и -любого потребителя — что прямо требуется вопросом 6, — и снимает питон из +любого потребителя — что прямо требуется вопросом 5, — и снимает питон из зависимостей репозиториев-потребителей. -Порядок обратный ожидаемому: пока вопрос 6 не сделан, инструмент всё равно +Порядок обратный ожидаемому: пока вопрос 5 не сделан, инструмент всё равно работает против одного конкретного канона, и независимый релизный цикл ему -нечего обслуживать. Сначала 6, потом 10. Разделение из вопроса 7 при этом +нечего обслуживать. Сначала 5, потом 9. Разделение из вопроса 6 при этом дешевле заложить сразу, чем отпиливать потом.