обвязка: идентификаторы правил описаны через префиксы
- LANGUAGE.md: раздел «Идентификаторы» переписан под префиксы, в список машинных проверок добавлена сверка с реестром - GUIDE.md перенумерован под префикс META, «номер правила» заменён на «идентификатор»
This commit is contained in:
+37
-21
@@ -12,8 +12,8 @@
|
||||
Не ради строгости. Три конкретные вещи, которые без адресуемых правил не
|
||||
работают:
|
||||
|
||||
- **Механизация.** Регион `механизировано` должен говорить «правило R4
|
||||
проверяет `archrules`», а не «`AUTOINCREMENT` в новых миграциях —
|
||||
- **Механизация.** Регион `механизировано` должен говорить «правило
|
||||
`MIGR-4` проверяет `archrules`», а не «`AUTOINCREMENT` в новых миграциях —
|
||||
`archrules`»: во втором случае читатель сам догадывается, к какому
|
||||
утверждению это относится, и догадывается по-разному.
|
||||
- **Отступления.** «У нас не так» бесполезно, пока не сказано, что именно
|
||||
@@ -28,7 +28,7 @@
|
||||
## Единица — правило
|
||||
|
||||
```markdown
|
||||
### R5. Разбор внешнего идентификатора на границе
|
||||
### KEYS-5. Разбор внешнего идентификатора на границе
|
||||
|
||||
**ДОЛЖЕН.** Идентификатор, пришедший снаружи, проходит разбор до запроса
|
||||
к базе.
|
||||
@@ -38,8 +38,8 @@
|
||||
существующую запись — отладка такого случая стоит дороже, чем сам разбор.
|
||||
```
|
||||
|
||||
Четыре обязательные части: **номер**, **заголовок**, **модальность с
|
||||
нормой**, **почему**. Норма — одна фраза; если в неё не влезает, это два
|
||||
Четыре обязательные части: **идентификатор**, **заголовок**, **модальность
|
||||
с нормой**, **почему**. Норма — одна фраза; если в неё не влезает, это два
|
||||
правила.
|
||||
|
||||
## Правило без «почему» не принимается
|
||||
@@ -79,7 +79,7 @@
|
||||
Модальность живёт на **правиле**, а не на файле. Прежний файловый статус
|
||||
(`status: рекомендуемая` / `обязательная` в шапке) отменён: он неизбежно
|
||||
врал, потому что один файл смешивает жёсткие требования с советами. В шапке
|
||||
остаются только `extends` и служебные ключи копии.
|
||||
остаются только `prefix`, `extends` и служебные ключи копии.
|
||||
|
||||
Мы **не используем SHALL и прочие английские ключевые слова**. Они заняты
|
||||
спецификациями (OpenSpec), и общий словарь стирал бы границу «конвенция —
|
||||
@@ -87,13 +87,26 @@
|
||||
|
||||
## Идентификаторы
|
||||
|
||||
- Формат — `R<номер>`, сквозная нумерация внутри файла, начиная с `R1`.
|
||||
- Строка таблицы, если на неё нужно ссылаться отдельно, — `R5.1`, `R5.2`.
|
||||
- **Номера стабильны и не переиспользуются.** Удалённое правило оставляет
|
||||
дыру в нумерации; занимать её новым правилом нельзя — иначе ссылка из
|
||||
чужого репозитория начнёт указывать на другое утверждение.
|
||||
- Глобальный адрес — путь файла плюс номер: `arch/db-identifiers.md R5`.
|
||||
В пределах одного файла достаточно `R5`.
|
||||
- Формат — `<ПРЕФИКС>-<номер>`: `KEYS-5`, `SLOG-27`. Префикс принадлежит
|
||||
файлу, нумерация внутри файла сквозная и начинается с единицы.
|
||||
- Строка таблицы, если на неё нужно ссылаться отдельно, — `KEYS-5.1`,
|
||||
`KEYS-5.2`.
|
||||
- **Идентификатор глобален.** Префикс уникален по всему канону, поэтому
|
||||
путь файла в ссылке не нужен: `KEYS-5` адресует правило одинаково изнутри
|
||||
файла, из соседней конвенции и из чужого репозитория. В собранной копии
|
||||
слои разных осей лежат в одном документе, так что ссылка на базовый слой
|
||||
из языкового вообще никуда не ведёт — правило рядом.
|
||||
- **Идентификаторы стабильны и не переиспользуются.** Удалённое правило
|
||||
оставляет дыру в нумерации; занимать её новым нельзя — иначе ссылка из
|
||||
чужого репозитория начнёт указывать на другое утверждение. То же
|
||||
относится к префиксам: выбывшие хранит `conventions/prefixes.toml`.
|
||||
- Префикс **выбирается под файл, а не выводится по формуле**: он нужен,
|
||||
чтобы по нему искать, а не чтобы его разбирать. Выводимый префикс вдобавок
|
||||
привязал бы идентификатор к таксономии, которую канон перестраивает, и
|
||||
упёрся бы в потолок из числа букв алфавита.
|
||||
- Перенос правила в другой файл — смысловое изменение, а не переименование:
|
||||
новый файл означает новый префикс и новую нумерацию. Переезд самого файла
|
||||
между осями идентификаторы не трогает.
|
||||
|
||||
Порядок правил в файле выбирается по читаемости, не по номерам: номер — это
|
||||
идентификатор, а не позиция.
|
||||
@@ -105,7 +118,7 @@
|
||||
чтобы оно не выглядело недописанным, место нормы занимает отметка:
|
||||
|
||||
```markdown
|
||||
### R6. Дефолтов времени в схеме БД нет
|
||||
### MIGR-6. Дефолтов времени в схеме БД нет
|
||||
|
||||
**МЕХАНИЗИРОВАНО.** Проверяется общим правилом линтера; формулировка
|
||||
удалена, потому что дублировала работающую проверку.
|
||||
@@ -113,7 +126,7 @@
|
||||
**Почему.** Дефолт превращает забытую вставку в тихо работающий код…
|
||||
```
|
||||
|
||||
- Номер и заголовок сохраняются: ссылки из репозиториев продолжают
|
||||
- Идентификатор и заголовок сохраняются: ссылки из репозиториев продолжают
|
||||
указывать на то же утверждение.
|
||||
- «Почему» остаётся навсегда — линтер сообщает, что нарушено, но не
|
||||
сообщает, зачем правило существует, и без обоснования нельзя понять,
|
||||
@@ -175,11 +188,11 @@ AND тик фонового цикла упал по той же причине
|
||||
|
||||
```markdown
|
||||
<!-- local:механизировано -->
|
||||
R2, R4 — `internal/archrules` (проверяются в новых миграциях).
|
||||
MIGR-2, MIGR-4 — `internal/archrules` (проверяются в новых миграциях).
|
||||
<!-- /local -->
|
||||
|
||||
<!-- local:отступления -->
|
||||
R6 — не соблюдается в легаси-таблицах `show_history`, `queue`: составные
|
||||
MIGR-6 — не соблюдается в легаси-таблицах `show_history`, `queue`: составные
|
||||
ключи там появились до конвенции, переписывание требует миграции данных.
|
||||
<!-- /local -->
|
||||
```
|
||||
@@ -191,12 +204,15 @@ R6 — не соблюдается в легаси-таблицах `show_histor
|
||||
|
||||
Сейчас не реализовано; список — на будущее для `conv`:
|
||||
|
||||
- префикс в шапке файла совпадает с реестром, состоит из четырёх заглавных
|
||||
латинских букв и не значится в списке выбывших;
|
||||
- заголовки правил файла используют только его собственный префикс;
|
||||
- номера уникальны внутри файла и не имеют пропусков вниз (новое правило
|
||||
берёт следующий свободный, а не первый освободившийся);
|
||||
- у каждого `### R<n>` есть модальное слово (или отметка МЕХАНИЗИРОВАНО) и
|
||||
блок «Почему»;
|
||||
- ссылки вида `R<n>` в локальных регионах копии указывают на правила,
|
||||
которые в каноне ещё существуют;
|
||||
- у каждого `### <ПРЕФИКС>-<n>` есть модальное слово (или отметка
|
||||
МЕХАНИЗИРОВАНО) и блок «Почему»;
|
||||
- ссылки вида `<ПРЕФИКС>-<n>` — хоть в тексте канона, хоть в локальных
|
||||
регионах копии — указывают на правила, которые ещё существуют;
|
||||
- модальные слова не встречаются вне правил.
|
||||
|
||||
## Порядок перевода
|
||||
|
||||
Reference in New Issue
Block a user