av
d211052914
- docs/conventions/ с индексом: чем конвенция отличается от ADR и drafts, статусы (рекомендуемая / обязательная), когда заводить - app-directories.md: конфигурация / данные / кеш по принципу создания и ценности; из категорий выводится backup-targets - раздел «Конвенции» в AGENTS.md со ссылкой на склад
47 lines
2.8 KiB
Markdown
47 lines
2.8 KiB
Markdown
# Конвенции
|
||
|
||
Склад договорённостей о том, **как делать однотипные вещи** в этом
|
||
репозитории. Одна конвенция — один файл.
|
||
|
||
Конвенция описывает повторяющийся выбор: как называть директории, как
|
||
раскладывать данные, как оформлять шаблоны. Она отвечает на вопрос «как
|
||
принято», а не «что здесь происходит».
|
||
|
||
Чем отличается от соседей:
|
||
|
||
- [`../adr/`](../adr) — **решение**, принятое однажды и постфактум
|
||
(«почему выбрали Authelia, а не Keycloak»). Запись неизменяема.
|
||
- [`../drafts/`](../drafts) — оперативная хроника и черновики («что
|
||
собираюсь сделать»).
|
||
- `conventions/` — **правило на будущее**, применяемое многократно.
|
||
Живой документ: правится, когда договорённость меняется.
|
||
|
||
## Статус
|
||
|
||
Каждая конвенция начинается со строки статуса:
|
||
|
||
- **Рекомендуемая** — так стоит делать в новом коде; существующий код
|
||
переезжает по мере касания, отдельной кампанией не переписывается.
|
||
- **Обязательная** — нарушение считается ошибкой; по возможности
|
||
проверяется линтером или хуком, а не вниманием.
|
||
|
||
Конвенция без механической проверки держится только на внимании — это
|
||
нормально для рекомендуемой и плохо для обязательной.
|
||
|
||
## Когда заводить
|
||
|
||
Когда одно и то же решение принимается третий раз и каждый раз чуть
|
||
по-другому. Единичный выбор — не конвенция; если он ещё и был спорным,
|
||
ему место в ADR.
|
||
|
||
## Соглашения
|
||
|
||
- Имя файла — kebab-case, по теме: `app-directories.md`.
|
||
- В теле честно перечислены отступления, которые уже есть в коде, —
|
||
иначе документ описывает не репозиторий, а пожелание.
|
||
|
||
## Список
|
||
|
||
- [Категории директорий приложения](app-directories.md) — конфигурация /
|
||
данные / кеш: делим по тому, кто создаёт и что будет при потере.
|