исправлены дефекты формулировок в конвенциях
- убраны неверные утверждения: покрытие forbidigo сужено до честного, таблица классов доменного отказа больше не претендует на полноту, механизация не подаётся как факт канона - введены недостающие определения (доменная и внешняя границы, объявление пути), критерий постоянного поля сведён к одному на R16.1 и R17 - kebab-case имени файла убран из правил в прозу: обоснование не формулировалось, номер R16 оставлен свободным
This commit is contained in:
@@ -26,6 +26,15 @@
|
||||
- `docs/conventions/` — **правило на будущее**, применяемое многократно.
|
||||
Живой документ: правится, когда договорённость меняется.
|
||||
|
||||
## Оформление
|
||||
|
||||
Имя файла — kebab-case по теме: `app-directories.md`. Правилом это не
|
||||
записано: обоснование сводится к «чтобы адрес правила
|
||||
(`stack/ansible/app-directories.md R4`) писался одним способом», а
|
||||
проверить нарушение всё равно проще глазом, чем сформулировать норму. Номер
|
||||
R16, под которым это правило существовало, оставлен свободным и не
|
||||
переиспользуется.
|
||||
|
||||
## Канон и копии
|
||||
|
||||
Файлы в `docs/conventions/` с шапкой `origin:` — копии из общего канона
|
||||
@@ -106,6 +115,10 @@
|
||||
это честно, а ДОЛЖЕН при этом обещает то, чего не делает, и через несколько
|
||||
таких случаев обесценивает остальные ДОЛЖЕН в файле.
|
||||
|
||||
Отсюда следствие: правило, машинная проверка которого невозможна в принципе
|
||||
(вкус формулировки, выбор границы, суждение о ситуации), не может быть
|
||||
ДОЛЖЕН — его модальность СЛЕДУЕТ по построению, а не по слабости.
|
||||
|
||||
### R7. Факт механизации фиксируется в локальном регионе со ссылкой на номер
|
||||
|
||||
**ДОЛЖЕН.** Регион `механизировано` называет номер правила и конкретную
|
||||
@@ -127,6 +140,11 @@
|
||||
говорит о прочих, поэтому удалять по факту «у нас уже проверяется» —
|
||||
значит чинить свой файл за чужой счёт.
|
||||
|
||||
Списка подписчиков канон по построению не знает, поэтому факт «механизировано
|
||||
у всех» устанавливается обходом репозиториев вручную — это часть работы по
|
||||
удалению нормы, а не то, что можно проверить машиной (см. `LANGUAGE.md`,
|
||||
состояние МЕХАНИЗИРОВАНО).
|
||||
|
||||
### R9. Общая механизация разрешает удалить норму из канона
|
||||
|
||||
**ДОПУСКАЕТСЯ.** Правило, уехавшее в общий конфиг линтера или в общую роль,
|
||||
@@ -205,16 +223,6 @@
|
||||
правила в каноне, которую чинят один раз для всех, или лишнюю подписку,
|
||||
где файл просто не нужен. Оставленная отступлением, она прячет обе.
|
||||
|
||||
### R16. Имя файла — kebab-case по теме
|
||||
|
||||
**СЛЕДУЕТ.** `app-directories.md`, а не вариации регистра и разделителя.
|
||||
|
||||
**Почему.** Имя файла — часть глобального адреса правила
|
||||
(`stack/ansible/app-directories.md R4`) и значение ключа `origin` в каждой
|
||||
копии. Один способ записи избавляет от нескольких написаний одного адреса,
|
||||
а ошибка в адресе обнаруживается только тем, кто по нему пришёл и ничего не
|
||||
нашёл.
|
||||
|
||||
### R17. Репо-специфичная часть «Связано» — в локальном регионе
|
||||
|
||||
**ДОЛЖЕН.** Раздел «Связано» стоит в конце файла; канонические ссылки — в
|
||||
|
||||
Reference in New Issue
Block a user