guide: правила самодостаточности нормы и формы ссылки
- META-20: норму можно исполнить, имея один файл; на чужую тему смотрят только «Почему», «Связано» и разграничение области — подписка это произвольное подмножество, графа зависимостей нет по построению - META-21: ссылка ведёт на имя темы или идентификатор правила; путь файла канона умирает при сборке, потому что слои темы становятся секциями
This commit is contained in:
@@ -97,6 +97,36 @@ prefix: META
|
||||
с первого дня. «Так сделано у нас» — содержимое региона отступлений, где оно
|
||||
и локально, и проверяемо.
|
||||
|
||||
### META-20. Норма самодостаточна, наружу смотрит только обоснование
|
||||
|
||||
**ДОЛЖЕН.** Норму правила можно исполнить, имея один этот файл. Ссылка на
|
||||
правило чужой темы допустима в «Почему», в «Связано» и в разграничении
|
||||
области действия — но не в самой норме. Если норме нужен концепт соседней
|
||||
темы, он коротко повторяется здесь, а сосед называется в «Почему» как
|
||||
источник решения.
|
||||
|
||||
**Почему.** Репозиторий подписывается на произвольное подмножество
|
||||
конвенций, и графа зависимостей у него нет по построению. Норма, которую
|
||||
нельзя исполнить без отсутствующего файла, делает такое подмножество
|
||||
невалидным молча: читатель видит связный текст и не замечает, что часть
|
||||
нормы не определена. Обоснование, потерявшее адресата, деградирует честно —
|
||||
пропадает перекрёстная проверка, смысл остаётся. Цена повтора — риск
|
||||
разойтись с источником; она платится сознательно и видна, в отличие от
|
||||
скрытой зависимости.
|
||||
|
||||
### META-21. Ссылка ведёт на тему или на правило, но не на путь в каноне
|
||||
|
||||
**ДОЛЖЕН.** На соседнюю конвенцию ссылаются именем темы (конвенция
|
||||
`logging`), на конкретное правило — идентификатором (`SLOG-27`), на другой
|
||||
слой своей же темы — словами «базовый слой». Путь файла канона в тексте
|
||||
конвенции не употребляется.
|
||||
|
||||
**Почему.** В репозитории конвенция лежит собранной: слои одной темы — это
|
||||
секции одного файла, и пути `lang/go/logging.md` там не существует. Ссылка
|
||||
на путь канона умирает при сборке, причём молча — текст остаётся связным.
|
||||
Имя темы и идентификатор правила переживают и сборку, и переезд файла между
|
||||
осями.
|
||||
|
||||
### META-5. Расхождение кода с правилом — отступление, а не повод переписать правило
|
||||
|
||||
**ДОЛЖЕН.** Правило правится, только когда неверно по существу: содержит
|
||||
|
||||
@@ -213,6 +213,8 @@ MIGR-6 — не соблюдается в легаси-таблицах `show_hi
|
||||
МЕХАНИЗИРОВАНО) и блок «Почему»;
|
||||
- ссылки вида `<ПРЕФИКС>-<n>` — хоть в тексте канона, хоть в локальных
|
||||
регионах копии — указывают на правила, которые ещё существуют;
|
||||
- чужой префикс не встречается в абзаце с модальностью (META-20);
|
||||
- путь файла канона не встречается в тексте конвенции (META-21);
|
||||
- модальные слова не встречаются вне правил.
|
||||
|
||||
## Порядок перевода
|
||||
|
||||
Reference in New Issue
Block a user