From fe61ecd6c545d576d94b2f461adda1a41a3dcb68 Mon Sep 17 00:00:00 2001 From: Anton Vakhrushev Date: Sun, 26 Jul 2026 15:34:49 +0300 Subject: [PATCH] =?UTF-8?q?guide:=20=D1=8F=D0=B7=D1=8B=D0=BA=20=D1=83?= =?UTF-8?q?=D0=BF=D0=BE=D1=82=D1=80=D0=B5=D0=B1=D0=BB=D1=8F=D0=B5=D1=82?= =?UTF-8?q?=D1=81=D1=8F,=20=D0=B7=D0=BD=D0=B0=D1=87=D0=B8=D1=82=20=D0=B8?= =?UTF-8?q?=20=D0=BF=D1=80=D0=BE=D0=B2=D0=B5=D1=80=D1=8F=D0=B5=D1=82=D1=81?= =?UTF-8?q?=D1=8F=20=D0=BA=D0=B0=D0=BA=20=D0=B2=20=D0=BA=D0=BE=D0=BD=D0=B2?= =?UTF-8?q?=D0=B5=D0=BD=D1=86=D0=B8=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - проверки разведены по роли слова: то, что язык употребляет (конвенции и GUIDE.md), проверяется; то, что цитирует (LANGUAGE.md, README.md), — нет - список машинных проверок разбит на форму правила и распространение: вторая группа (тема в шапке, пути канона, чужие префиксы, локальные X) касается только того, что едет к потребителю - в GUIDE.md добавлена строка о версии языка и убрано заглавное СЛЕДУЕТ из вводной прозы «Оформления» — единственное нарушение, которое исключение прятало --- CLAUDE.md | 6 ++++++ GUIDE.md | 9 ++++++++- LANGUAGE.md | 38 +++++++++++++++++++++------------- TODO.md | 56 ++++++++++++++++++--------------------------------- manifest.toml | 6 +++--- 5 files changed, 61 insertions(+), 54 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a0c6b84..719d127 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -143,6 +143,12 @@ code in this repository. проверять машиной». Ни одна из проверок не реализована, поэтому при ревью их выполняют чтением. +Проверяется всё, что язык **употребляет**: конвенции и `GUIDE.md` (он несёт +правила META и строку о версии языка). `LANGUAGE.md` и `README.md` язык +цитируют — ключевые слова в них предмет описания, а не норма. Проверки +распространения (тема в шапке, самодостаточность нормы, отсутствие путей +канона) касаются только конвенций: обвязка к потребителю не едет. + ## Коммиты Русский, строчная буква, без точки в конце, прошедшее время или страдательный diff --git a/GUIDE.md b/GUIDE.md index e1374fc..2147487 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -12,6 +12,13 @@ prefix: META [LANGUAGE.md](LANGUAGE.md). Здесь — про то, зачем конвенции заводятся, где живут и как соотносятся с соседними видами документов. +Правила ниже записаны тем же языком, что и сами конвенции, и проверяются так +же. + +Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и метки +ПОЧЕМУ и МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — +тогда и только тогда, когда написаны заглавными. + ## Область действия Правила ниже адресованы автору конвенции — тому, кто заводит новый файл или @@ -36,7 +43,7 @@ prefix: META записано, и это случай META-25: регуляркой имя проверяется тривиально, но вреда от нарушения нет — тема объявлена в шапке (META-28), и сборка идёт по объявленному имени, а не по имени файла. Значит, и высшей модальности нет, а -на СЛЕДУЕТ такое правило не окупает строчку. +ступенью ниже такое правило не окупает строчку. ## Канон и копии diff --git a/LANGUAGE.md b/LANGUAGE.md index cf87a60..b4e81c7 100644 --- a/LANGUAGE.md +++ b/LANGUAGE.md @@ -471,21 +471,21 @@ XMIG-6 не соблюдается в легаси-таблицах `show_histor ## Что стоит проверять машиной -Проверки применяются к файлам конвенций; обвязка канона в них не входит — -она ключевые слова цитирует, а не употребляет. Ни одна пока не реализована, -поэтому при ревью их выполняют чтением. +Проверке подлежит всё, что язык **употребляет**: файлы конвенций и документ, +которым канон сам себя ведёт (в этом каноне — `GUIDE.md`, префикс META). Файл, +который язык **цитирует**, — это описание вроде текущего: ключевые слова стоят +в нём как предмет разговора, а не как норма, и проверки к нему не применяются. +Различает не расположение файла, а роль слова в нём. -Разбором текста: +Ни одна проверка пока не реализована, поэтому при ревью их выполняют чтением. + +**Форма правила** — разбором текста, в любом файле, который язык употребляет: - модальные и служебные слова принадлежат объявленному словарю канона, а не смеси словарей; - префикс в шапке файла совпадает с манифестом набора, состоит из четырёх - заглавных - латинских букв, не начинается на `X` и не значится в списке выбывших; -- шапка файла несёт имя темы, и это имя стоит в манифесте набора — среди - живых, а не среди выбывших; -- имя темы, названное в ссылке или в подписке потребителя, тоже разрешается по - манифесту: ссылка на снятую тему не проходит молча; + заглавных латинских букв, не начинается на `X` и не значится в списке + выбывших; - заголовки правил файла используют только его собственный префикс; - номера уникальны внутри файла и не имеют пропусков вниз (новое правило берёт следующий свободный, а не первый освободившийся); @@ -494,22 +494,32 @@ XMIG-6 не соблюдается в легаси-таблицах `show_histor - вводная проза содержит строку о версии языка; - ссылки вида `<ПРЕФИКС>-` — хоть в тексте канона, хоть в локальной части копии — указывают на правила, которые ещё существуют; -- префиксы локальных правил копии начинаются на `X`; - заглавные модальные слова не встречаются вне областей правил (область — от заголовка правила до следующего заголовка) — кроме строки о версии языка, которая их перечисляет по назначению; - модальная метка стоит первой в своём абзаце: заглавное слово в середине - фразы — упоминание ступени, а не вторая норма правила; + фразы — упоминание ступени, а не вторая норма правила. + +**Распространение** — разбором текста, только в файлах конвенций: эти проверки +о том, что документ уезжает к потребителю, а документ, которым канон ведёт +себя, не уезжает никуда. + +- шапка файла несёт имя темы, и это имя стоит в манифесте набора — среди + живых, а не среди выбывших; +- имя темы, названное в ссылке или в подписке потребителя, тоже разрешается по + манифесту: ссылка на снятую тему не проходит молча; +- префиксы локальных правил копии начинаются на `X`; - префикс **чужой темы** не встречается в абзаце с модальностью (META-20); префикс арх-слоя своей темы там допустим (META-24), префикс другого языка или стека — нет; - путь файла канона не встречается в тексте конвенции (META-21). -Чтением, потому что машине не даётся: +**Чтением**, потому что машине не даётся: - строки таблицы взаимоисключающи либо политика совпадения объявлена; - перечисленные в таблице случаи покрывают область действия; -- норма исполнима без обращения к другим файлам; +- норма исполнима без обращения к другим файлам (в файлах конвенций: они + уезжают по одной, а обвязка ссылается на соседей свободно); - обоснование отвечает на «что сломается», а не пересказывает норму; - хвост обоснования не вводит требований, которых нет в блоке нормы. diff --git a/TODO.md b/TODO.md index 412a005..aca1f14 100644 --- a/TODO.md +++ b/TODO.md @@ -4,28 +4,12 @@ решения. Закрытый вопрос отсюда удаляется — принятое решение живёт в `README.md`, `GUIDE.md` или `LANGUAGE.md`, а не в этом файле. -Две секции: сначала язык и подход, потом канон с тулингом. Пункты 1–5 +Две секции: сначала язык и подход, потом канон с тулингом. Пункты 1–4 пришли из внешнего ревью описания языка и проверены по файлам на месте. # Язык и подход -## 1. GUIDE выведен из-под проверок ложным основанием - -`LANGUAGE.md` исключает обвязку из проверок формулировкой «она ключевые слова -цитирует, а не употребляет». Для `GUIDE.md` это неверно: META-правила -употребляют ДОЛЖЕН нормативно, а префикс META стоит в `[prefixes.live]` -манифеста набора, где прямо сказано, что правила записаны тем же языком. - -Три следствия. META-правила не попадают ни под одну проверку формы. В -`GUIDE.md` нет строки о версии языка, то есть у META-правил формально нет -ключа к толкованию. И нарушение уже есть: раздел «Оформление» содержит -заглавное СЛЕДУЕТ во вводной прозе — в файле конвенции это было бы -нарушением, а исключение обвязки его прячет. - -Честнее развести: `GUIDE.md` язык **употребляет** и проверяется как -конвенция, `LANGUAGE.md` и `README.md` — цитируют. - -## 2. МЕХАНИЗИРОВАНО не переживает нового подписчика +## 1. МЕХАНИЗИРОВАНО не переживает нового подписчика META-8 запрещает удалять норму, пока механизирована не у всех, и защищает тем самым потребителей, существующих **на момент удаления**. Будущих не @@ -43,7 +27,7 @@ META-8 запрещает удалять норму, пока механизир в тексте канона, то есть ровно то, что запрещает META-4. Либо это законное исключение, и тогда его надо назвать, либо конфликт. -## 3. Семантика ключевых слов в копию не едет +## 2. Семантика ключевых слов в копию не едет Строка о версии языка перечисляет слова, но не их значения, а всё нетривиальное в шкале живёт только в `LANGUAGE.md`, который в репозиторий не @@ -59,7 +43,7 @@ META-8 запрещает удалять норму, пока механизир копиями короткую выжимку семантики; расширить строку о версии до двух-трёх предложений; или признать ограничение и записать его явно. -## 4. Две «механические» проверки без источника данных +## 3. Две «механические» проверки без источника данных В списке «разбором текста» стоят два пункта, которые без дополнительного реестра нерешаемы: @@ -70,13 +54,13 @@ META-8 запрещает удалять норму, пока механизир - **«ссылки указывают на правила, которые ещё существуют»** — упоминание снятого номера в прозе выглядит как висячая ссылка. -`GUIDE.md` завёл для себя раздел «Освободившиеся номера», но язык не требует -такой таблицы от конвенций, а манифест набора хранит только темы и префиксы. -Пока -реестр снятых номеров не объявлен частью языка, оба пункта принадлежат -списку «чтением». +`GUIDE.md` завёл для себя раздел «Освободившиеся номера» — и, поскольку он +теперь проверяется как конвенция, это единственный живой пример такого +реестра. Языком он всё равно не объявлен: от конвенций такой таблицы не +требуют, а манифест набора хранит только темы и префиксы. Пока реестр снятых +номеров не объявлен частью языка, оба пункта принадлежат списку «чтением». -## 5. Натяжки в опоре на стандарты +## 4. Натяжки в опоре на стандарты Три места, где источнику приписано чуть больше, чем в нём есть: @@ -95,7 +79,7 @@ META-8 запрещает удалять норму, пока механизир Остальное в таблице проверку выдержало, включая вторую половину `MAY` из BCP 14 и списки эквивалентных словесных форм ISO Directives. -## 6. Одиннадцать таблиц не прочитаны на взаимоисключительность +## 5. Одиннадцать таблиц не прочитаны на взаимоисключительность `LANGUAGE.md` объявил, что строки таблицы решений взаимоисключающи по умолчанию, а иной порядок объявляется явно. Объявление не делает таблицы @@ -110,7 +94,7 @@ BCP 14 и списки эквивалентных словесных форм IS Работа читательская, машине не даётся; в список проверок она уже записана в разделе «Чтением, потому что машине не даётся». -## 7. Описание языка отдельно от набора конвенций +## 6. Описание языка отдельно от набора конвенций `LANGUAGE.md` и `GUIDE.md` описывают, **как** пишутся конвенции; `conventions/` — **один конкретный** набор. Сейчас они склеены в одном @@ -135,7 +119,7 @@ BCP 14 и списки эквивалентных словесных форм IS # Канон, тулинг, подключение -## 8. Тулинг: две разные задачи в одном `conv` +## 7. Тулинг: две разные задачи в одном `conv` Сейчас в `conv` смешаны две категории работы, и они расходятся по всему — по частоте запуска, по тому, кто запускает, и по тому, что считается @@ -166,7 +150,7 @@ BCP 14 и списки эквивалентных словесных форм IS ссылках: это установка, а не целостность, но список подписок ему нужен из манифеста. -Часть проверок из этого списка сейчас нереализуема по причине из вопроса 4, +Часть проверок из этого списка сейчас нереализуема по причине из вопроса 3, так что порядок такой: сначала язык, потом чекер. Перед тем как переписывать, стоит посмотреть на два готовых прототипа: @@ -174,7 +158,7 @@ BCP 14 и списки эквивалентных словесных форм IS манифеста и `vendir.yml` — как пример того, где проходит граница между «чего хочу» и «что получил». -## 9. Пары слоёв и темы без базы +## 8. Пары слоёв и темы без базы Отложено сознательно, но список стоит держать перед глазами: @@ -195,7 +179,7 @@ BCP 14 и списки эквивалентных словесных форм IS - Вынос арх-ядра из `errors` и `logging` закроет две хрупкие ссылки из `web-ui` (стек) в go-слой — единственные ссылки стек → язык в каноне. -## 10. Подключение к репозиториям +## 9. Подключение к репозиториям Ничего ещё не подключено. Кандидаты — jellybit и pet-project-server. Понадобится: заполнить локальную часть копий тем, что сейчас в этих @@ -204,7 +188,7 @@ BCP 14 и списки эквивалентных словесных форм IS строка в `AGENTS.md` каждого потребителя про то, что файлы в `docs/conventions/` — копии. -## 11. Тулинг на Go, живущий независимо +## 10. Тулинг на Go, живущий независимо Сейчас `conv` — питоновский скрипт внутри канона, то есть тулинг и данные в одном репозитории и правятся одним движением. Мысль: вынести в отдельный @@ -213,10 +197,10 @@ Go-бинарь со своим релизным циклом, ставить ч Что за этим стоит помимо вкуса: независимый бинарь физически не даёт править инструмент «заодно» с правкой конвенции, работает против **любого** канона и -любого потребителя — что прямо требуется вопросом 7, — и снимает питон из +любого потребителя — что прямо требуется вопросом 6, — и снимает питон из зависимостей репозиториев-потребителей. -Порядок обратный ожидаемому: пока вопрос 7 не сделан, инструмент всё равно +Порядок обратный ожидаемому: пока вопрос 6 не сделан, инструмент всё равно работает против одного конкретного канона, и независимый релизный цикл ему -нечего обслуживать. Сначала 7, потом 11. Разделение из вопроса 8 при этом +нечего обслуживать. Сначала 6, потом 10. Разделение из вопроса 7 при этом дешевле заложить сразу, чем отпиливать потом. diff --git a/manifest.toml b/manifest.toml index ba18f59..4778c9e 100644 --- a/manifest.toml +++ b/manifest.toml @@ -91,9 +91,9 @@ GTIM = "conventions/lang/go/time.md" ANSD = "conventions/stack/ansible/app-directories.md" HTMX = "conventions/stack/htmx/web-ui.md" -# Обвязка набора: не синхронизируется в репозитории, но правила записаны тем -# же языком и цитируются по номерам, поэтому префикс нужен. Темы у неё нет — -# подписаться на обвязку нельзя, она не едет к потребителю. +# Документ, которым канон ведёт себя сам: к потребителю не едет, но правила в +# нём записаны тем же языком, цитируются по номерам и проверяются как +# конвенция — отсюда префикс. Темы у него нет: подписаться на него нельзя. META = "GUIDE.md" [prefixes.retired]