Amansultan

Appearance

ADR-4: Конвенция сообщений коммитов ​

Статус ​

На согласовании (04.09.2025)

Цель ​

Обеспечить понятную, единообразную и полезную историю изменений в git.

Основные проблемы, которые решает конвенция:

  • разные стили сообщений от разработчиков затрудняют чтение истории,
  • сложно связать изменения с задачами и issue,
  • невозможно автоматически собирать CHANGELOG и версии.

Решение ​

Когда делать коммит ​

  • После каждого логического шага (одна фича, один багфикс).
  • Только после успешного прохождения линтеров.
  • Перед мёрджем или ребейзом, чтобы облегчить разрешение конфликтов.
  • Не дожидаясь конца дня — коммиты должны быть частыми и атомарными.

Что должно быть в одном коммите ​

  • Один логический кусок работы.
  • Atomic changes: код + тесты + документация вместе.
  • Без «мертвого» кода и экспериментальных правок.
  • Если меняется публичное API — обновить README / Swagger / Wiki.

Формат сообщений (Conventional Commits) ​


<type>(<scope>): <subject>

\[optional body]

\[optional footer]

Элементы формата ​

  • type — обязательно, категория изменений.
  • scope — необязательно, указывает модуль/компонент (auth, api, ui, db).
  • subject — обязательно, краткое описание (императив, ≤50 символов, без точки).
  • body — необязательно, подробное описание «что и почему», строки ≤72 символов.
  • footer — необязательно, служебная информация (ссылки на задачи, BREAKING CHANGE).

Типы (<type>) ​

  • feat — новая функциональность.
  • fix — исправление бага.
  • docs — документация.
  • style — форматирование, пробелы, нейминг, без изменения логики.
  • refactor — изменение структуры без новой функциональности и багфиксов.
  • perf — оптимизация производительности.
  • test — добавление или изменение тестов.
  • chore — задачи окружения: CI/CD, зависимости, скрипты.

Scope (<scope>) ​

  • Один модуль или компонент: auth, api, ui, db, ci, deploy.
  • Если область неочевидна или затрагиваются разные модули, scope можно опустить.

✅ Примеры ​

bash
git commit -m "feat(auth): добавить endpoint для входа пользователя

- Реализован POST /api/v1/auth/login
- Возвращается JWT-токен
- Добавлены unit-тесты и пример в README
bash
git commit -m "fix(ui): исправить обрезание текста в карточках товара

Текст с длинными названиями теперь переносится по словам,
пропорции карточки сохранены.
bash
git commit -m "chore(ci): обновить образ Docker до Node.js 18

- Базовый образ node:18-alpine
- Обновлены зависимости node-sass → sass

📋 Правило для код-ревью ​

  • Проверять, что сообщение коммита соответствует формату.
  • У коммита есть чёткая связь с задачей (issue, MR, или Closes #).
  • Не принимаются «мусорные» коммиты (fix bug, wip, update).

📌 Последствия ​

  • ✅ Понятная история изменений.
  • ✅ Связь изменений с задачами и issue.
  • ✅ Автоматическая генерация CHANGELOG и релизов.
  • ✅ Семантическое версионирование (SemVer) из коммитов.
  • ✅ Удобство код-ревью и отката изменений.
  • ❌ Требуется дисциплина при написании сообщений.