Files

T

docs: заведён склад конвенций, первая — категории директорий приложения

- docs/conventions/ с индексом: чем конвенция отличается от ADR и drafts,
  статусы (рекомендуемая / обязательная), когда заводить
- app-directories.md: конфигурация / данные / кеш по принципу создания и
  ценности; из категорий выводится backup-targets
- раздел «Конвенции» в AGENTS.md со ссылкой на склад

2026-07-25 13:52:00 +03:00

2.8 KiB

Raw Permalink Blame History

Конвенции

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

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

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

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

Статус

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

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

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

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

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

Соглашения

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

Список

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

2.8 KiB Raw Permalink Blame History Unescape Escape