Conventional Commits

Коротко: Соглашение о сообщениях коммитов с фиксированным форматом: <тип>(<область>): <краткое описание>, например feat(shop): ... или fix(chat): ....

Подробнее: Распространённые типы: feat (новая функция), fix (исправление ошибки), refactor (реструктуризация без изменения поведения), chore (обслуживание, например обновления зависимостей), perf (производительность). Делает историю коммитов машиночитаемой (например, для автоматических журналов изменений) и позволяет людям классифицировать её с одного взгляда.

Наш контекст: Для Emzett согласовано собственное соглашение — каждая «пачка» изменений получает сообщение коммита в этом формате на немецком языке, плюс дополнительный раздел «почему» с обоснованием решения.

Подробности

Полная структура

Помимо однострочного заголовка, полная спецификация знает необязательное тело (более подробное объяснение, обычно отделённое пустой строкой) и необязательные «нижние колонтитулы» (footers) для структурированной дополнительной информации — например, BREAKING CHANGE: ... для изменений, затрагивающих существующих пользователей кодовой базы, или Closes #123 для автоматической связи коммита с задачей (issue). ! сразу после типа/области (feat(api)!: ...) также помечает несовместимое изменение как сокращение подробного footer.

feat(shop)!: switch cart API to new response format
Old clients expecting the previous format break with this
update - only affects internal consumers of the API, no external ones.
BREAKING CHANGE: /api/cart now returns { items: [...] } instead of a
raw array.
Closes #142

Автоматизация благодаря машиночитаемой структуре

Настоящая практическая польза проявляется с инструментами, которые автоматически оценивают эту структуру: semantic-release и подобные инструменты могут выводить следующий номер версии по семантическому версионированию прямо из истории коммитов — коммит feat повышает минорную версию, коммит с BREAKING CHANGE — мажорную, fix — только патч-версию — и сразу генерировать из этого читаемый журнал изменений, без необходимости кому-либо вручную записывать, что изменилось в какой версии. Однако это надёжно работает, только если ДЕЙСТВИТЕЛЬНО каждый коммит в репозитории следует соглашению — даже один коммит без правильного префикса может нарушить автоматическую оценку или привести к неверно рассчитанному номеру версии.

Другие распространённые типы

Помимо основных типов (feat, fix, refactor, chore, perf), на практике закрепились и другие соглашения, хотя они не входят в официальную спецификацию: docs (только изменения документации), test (добавление/изменение тестов без изменения производственного кода), style (чисто косметические изменения вроде форматирования, без изменения поведения) и build/ci (изменения конфигурации сборки или конвейеров непрерывной интеграции). Область в скобках необязательна, но полезна, чтобы с одного взгляда видеть, какая часть кодовой базы затронута, не читая весь diff — в крупных проектах с чётко разделёнными модулями (например, shop, chat, auth) это делает историю коммитов гораздо удобнее для поиска.

Пределы соглашения

Conventional Commits обеспечивает структуру, но не качество — технически правильно оформленный коммит (fix(shop): fixed bug) всё равно может не говорить ничего по существу, если не хватает настоящей причины или обоснования. Поэтому многие команды дополняют чистую структуру тип/область обязанностью кратко объяснять в теле «почему» (а не только «что», которое и так можно прочитать из diff) — в долгосрочной перспективе сообщения коммитов часто единственное место, где остаются задокументированными мотивы решения.

См. также: Next.js App Router, Git