механизация больше не разрешает удалять норму
- META-9 снят: удаление оставляло подписчика, пришедшего после, без нормы и без проверки, а «механизировано у всех» канону не проверить — списка подписчиков у него нет по построению - META-8 переписан в запрет: норма остаётся в правиле, чем бы её ни проверяли; линтер сообщает, что нарушено, но не что требуется (META-6) - МЕХАНИЗИРОВАНО объявлена свойством репозитория: в тексте конвенции отметки нет, её место — запись о механизации ниже маркера (META-7)
This commit is contained in:
@@ -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: конвенция
|
||||
заводится, когда решение принимается третий раз.
|
||||
- Репозиторного в каноне нет вовсе: механизация, отступления и ссылки на код
|
||||
|
||||
@@ -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) |
|
||||
|
||||
+34
-30
@@ -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. Дефолтов времени в схеме БД нет
|
||||
<!-- conv:local -->
|
||||
|
||||
**ДОЛЖЕН. МЕХАНИЗИРОВАНО.** Проверяется общим правилом линтера;
|
||||
формулировка удалена, потому что дублировала работающую проверку.
|
||||
|
||||
**ПОЧЕМУ.** Дефолт превращает забытую вставку в тихо работающий код…
|
||||
XMIG-2, XMIG-4 — МЕХАНИЗИРОВАНО: `internal/archrules`, в новых миграциях.
|
||||
```
|
||||
|
||||
- Идентификатор и заголовок сохраняются: ссылки из репозиториев продолжают
|
||||
указывать на то же утверждение.
|
||||
- Модальность сохраняется, поэтому «все ли ДОЛЖЕН механизированы»
|
||||
остаётся вычислимым вопросом, а не предметом чтения всего канона.
|
||||
- Обоснование остаётся навсегда — линтер сообщает, что нарушено, но не
|
||||
сообщает, зачем правило существует, и без обоснования нельзя понять,
|
||||
когда проверку пора отменять.
|
||||
|
||||
Факт «механизировано у всех» устанавливается вручную: канон по построению
|
||||
не знает списка подписчиков, и обойти репозитории перед удалением нормы —
|
||||
часть работы, а не то, что можно проверить автоматически.
|
||||
Так у правила остаются оба атрибута сразу: обязательность — в норме, которая
|
||||
приезжает из набора и одинакова у всех, способ проверки — в записи, которая
|
||||
принадлежит репозиторию и у каждого своя.
|
||||
|
||||
## Таблицы решений
|
||||
|
||||
@@ -459,8 +462,7 @@ Directives, Part 2, по одной форме записи на ступень,
|
||||
```markdown
|
||||
<!-- conv:local -->
|
||||
|
||||
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
|
||||
- заголовки правил файла используют только его собственный префикс;
|
||||
- номера уникальны внутри файла и не имеют пропусков вниз (новое правило
|
||||
берёт следующий свободный, а не первый освободившийся);
|
||||
- у каждого `### <ПРЕФИКС>-<n>` есть модальное слово и блок ПОЧЕМУ;
|
||||
отметка МЕХАНИЗИРОВАНО стоит рядом с модальностью, а не вместо неё;
|
||||
- у каждого `### <ПРЕФИКС>-<n>` есть модальное слово, норма и блок ПОЧЕМУ:
|
||||
ни норма, ни обоснование не удаляются никогда (META-8, META-10);
|
||||
- вводная проза содержит строку о версии языка;
|
||||
- ссылки вида `<ПРЕФИКС>-<n>` — хоть в тексте канона, хоть в локальной части
|
||||
копии — указывают на правила, которые ещё существуют;
|
||||
@@ -509,6 +511,8 @@ XMIG-6 не соблюдается в легаси-таблицах `show_histor
|
||||
- имя темы, названное в ссылке или в подписке потребителя, тоже разрешается по
|
||||
манифесту: ссылка на снятую тему не проходит молча;
|
||||
- префиксы локальных правил копии начинаются на `X`;
|
||||
- отметки МЕХАНИЗИРОВАНО в тексте конвенции нет: её место — запись о
|
||||
механизации в локальной части копии (META-7);
|
||||
- префикс **чужой темы** не встречается в абзаце с модальностью (META-20);
|
||||
префикс арх-слоя своей темы там допустим (META-24), префикс другого языка
|
||||
или стека — нет;
|
||||
|
||||
@@ -179,7 +179,7 @@ origin: time
|
||||
```markdown
|
||||
<!-- conv:local -->
|
||||
|
||||
MIGR-2, MIGR-4 механизированы — `internal/archrules`.
|
||||
MIGR-2, MIGR-4 — МЕХАНИЗИРОВАНО: `internal/archrules`.
|
||||
MIGR-6 не соблюдается в `show_history`, `queue`: составные ключи там
|
||||
появились до конвенции, миграция данных не окупается.
|
||||
```
|
||||
|
||||
@@ -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 при этом
|
||||
дешевле заложить сразу, чем отпиливать потом.
|
||||
|
||||
Reference in New Issue
Block a user