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. Расхождение кода с правилом — отступление, а не повод переписать правило
|
### META-5. Расхождение кода с правилом — отступление, а не повод переписать правило
|
||||||
|
|
||||||
**ДОЛЖЕН.** Правило правится, только когда неверно по существу: содержит
|
**ДОЛЖЕН.** Правило правится, только когда неверно по существу: содержит
|
||||||
|
|||||||
@@ -213,6 +213,8 @@ MIGR-6 — не соблюдается в легаси-таблицах `show_hi
|
|||||||
МЕХАНИЗИРОВАНО) и блок «Почему»;
|
МЕХАНИЗИРОВАНО) и блок «Почему»;
|
||||||
- ссылки вида `<ПРЕФИКС>-<n>` — хоть в тексте канона, хоть в локальных
|
- ссылки вида `<ПРЕФИКС>-<n>` — хоть в тексте канона, хоть в локальных
|
||||||
регионах копии — указывают на правила, которые ещё существуют;
|
регионах копии — указывают на правила, которые ещё существуют;
|
||||||
|
- чужой префикс не встречается в абзаце с модальностью (META-20);
|
||||||
|
- путь файла канона не встречается в тексте конвенции (META-21);
|
||||||
- модальные слова не встречаются вне правил.
|
- модальные слова не встречаются вне правил.
|
||||||
|
|
||||||
## Порядок перевода
|
## Порядок перевода
|
||||||
|
|||||||
Reference in New Issue
Block a user