# Конвенции

Склад договорённостей о том, **как делать однотипные вещи** в этом
репозитории. Одна конвенция — один файл.

Конвенция описывает повторяющийся выбор: как называть директории, как
раскладывать данные, как оформлять шаблоны. Она отвечает на вопрос «как
принято», а не «что здесь происходит».

Чем отличается от соседей:

- [`../adr/`](../adr) — **решение**, принятое однажды и постфактум
  («почему выбрали Authelia, а не Keycloak»). Запись неизменяема.
- [`../drafts/`](../drafts) — оперативная хроника и черновики («что
  собираюсь сделать»).
- `conventions/` — **правило на будущее**, применяемое многократно.
  Живой документ: правится, когда договорённость меняется.

## Статус

Каждая конвенция начинается со строки статуса:

- **Рекомендуемая** — так стоит делать в новом коде; существующий код
  переезжает по мере касания, отдельной кампанией не переписывается.
- **Обязательная** — нарушение считается ошибкой; по возможности
  проверяется линтером или хуком, а не вниманием.

Конвенция без механической проверки держится только на внимании — это
нормально для рекомендуемой и плохо для обязательной.

## Когда заводить

Когда одно и то же решение принимается третий раз и каждый раз чуть
по-другому. Единичный выбор — не конвенция; если он ещё и был спорным,
ему место в ADR.

## Соглашения

- Имя файла — kebab-case, по теме: `app-directories.md`.
- В теле честно перечислены отступления, которые уже есть в коде, —
  иначе документ описывает не репозиторий, а пожелание.

## Список

- [Категории директорий приложения](app-directories.md) — конфигурация /
  данные / кеш: делим по тому, кто создаёт и что будет при потере.