guide: граница со спекой переписана на тест наблюдаемости вердикта
- «что против как» на пограничных правилах не работает: capability проверяется снаружи работающей системы, конвенция — только в исходном тексте, и отсюда расходятся направление, распространение и шкала - добавлен признак для спорного случая: обязательство перед внешним потребителем — в спеку, зависимость автора следующего патча — в конвенцию
This commit is contained in:
@@ -30,13 +30,31 @@ prefix: META
|
||||
|
||||
- `docs/adr/` — **решение**, принятое однажды и постфактум («почему выбрали
|
||||
Authelia, а не Keycloak»). Запись неизменяема.
|
||||
- `docs/specs/` и OpenSpec, где они есть, — **что** система делает,
|
||||
наблюдаемое поведение как контракт. Конвенция — **как** написан код;
|
||||
в спеки она не переносится, это не capability.
|
||||
- `docs/specs/` и OpenSpec, где они есть, — контракт наблюдаемого поведения.
|
||||
Конвенция в спеки не переносится: это не capability.
|
||||
- `docs/drafts/` — оперативная хроника и черновики, «что собираюсь сделать».
|
||||
- `docs/conventions/` — **правило на будущее**, применяемое многократно.
|
||||
Живой документ: правится, когда договорённость меняется.
|
||||
|
||||
Со спекой конвенцию путают чаще прочего, а «что против как» на границе не
|
||||
работает. Разводит их то, **где наблюдается вердикт**. У capability он виден
|
||||
снаружи работающей системы: подали вход, получили выход, совпало или нет. У
|
||||
конвенции — только в исходном тексте: снаружи не различить, обёрнута ошибка
|
||||
или проглочена и по какому признаку выбран уровень записи.
|
||||
|
||||
Отсюда расходится остальное. Спека едет за системой — изменилось поведение,
|
||||
меняется контракт; конвенция ведёт код, и факт «в приложении уже иначе»
|
||||
аргументом не считается (META-5), а утверждений о состоянии репозитория в ней
|
||||
нет вовсе (META-4). Спека принадлежит одной системе; конвенция ездит копиями
|
||||
и потому знает про темы, слои и локальную часть. Capability бинарна —
|
||||
реализована или нет; у конвенции есть ступени и постоянный список отступлений
|
||||
(META-13). Спеку пишут до кода, конвенцию — на третий раз (META-2).
|
||||
|
||||
Пограничное правило разбирается признаком внешнего потребителя. Формат логов,
|
||||
который собирает чужой агрегатор, — обязательство перед кем-то снаружи, и
|
||||
место ему в спеке. Если от правила зависит только автор следующего патча —
|
||||
это конвенция.
|
||||
|
||||
## Оформление
|
||||
|
||||
Имя файла повторяет имя темы: `app-directories.md`. Правилом это не
|
||||
|
||||
Reference in New Issue
Block a user