Conventional Commits

Стандарт форматирования сообщений коммитов: type(scope): description

Зачем нужно

  • Единообразные сообщения коммитов в команде
  • Автоматическая генерация CHANGELOG
  • Автоматическое определение версии (SemVer)
  • Понятная история изменений

Где используется

  • Открытые и корпоративные проекты
  • Совместно с semantic-release для автоматических релизов
  • В CI/CD для генерации release notes

Предпосылки

Формат

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Примеры

# Простой коммит
git commit -m "feat: добавить поиск по каталогу"

# С scope
git commit -m "fix(auth): исправить проверку JWT-токена"

# С телом и футером
git commit -m "feat(api): добавить пагинацию в endpoint /users

Реализована серверная пагинация с параметрами page и limit.
По умолчанию возвращается 20 записей.

Closes #42"

# Breaking change
git commit -m "feat(api)!: изменить формат ответа /users

BREAKING CHANGE: поле 'name' переименовано в 'fullName'.
Все клиенты API должны обновить парсинг."

Типы коммитов

Основные типы

Тип Описание SemVer
feat Новая функциональность MINOR (1.x.0)
fix Исправление бага PATCH (1.0.x)

Дополнительные типы

Тип Описание Пример
docs Документация Обновить README
style Форматирование (без изменения логики) Пробелы, точки с запятой
refactor Рефакторинг (без изменения поведения) Вынести функцию
test Добавление/изменение тестов Покрыть модуль тестами
chore Обслуживание проекта Обновить зависимости
perf Улучшение производительности Оптимизировать запрос
ci Изменения CI/CD Обновить GitHub Actions
build Изменения сборки Обновить webpack config
revert Откат коммита Откатить feat: ...

Breaking Changes

# Вариант 1: ! после типа
git commit -m "feat(api)!: убрать поле 'deprecated_field'"

# Вариант 2: BREAKING CHANGE в футере
git commit -m "feat(api): изменить формат ответа

BREAKING CHANGE: поле 'data' теперь массив вместо объекта"

Breaking change → MAJOR версия (x.0.0)

Scope (область)

Scope описывает часть кода, которая затронута:

feat(auth): ...         # модуль авторизации
fix(ui): ...            # пользовательский интерфейс
docs(api): ...          # документация API
refactor(database): ... # работа с базой данных
test(utils): ...        # утилиты
chore(deps): ...        # зависимости

Scope — опциональный. Используйте если в проекте есть чёткие модули.

Автоматизация

commitlint — проверка формата

# Установка
npm install -D @commitlint/cli @commitlint/config-conventional

# Конфигурация: commitlint.config.js
echo "module.exports = { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js

Интеграция с Husky

# Установка husky
npm install -D husky
npx husky init

# Добавить hook
echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg

Теперь некорректные сообщения будут отклонены:

git commit -m "обновил код"
# ⧗   input: обновил код
# ✖   subject may not be empty
# ✖   type may not be empty

git commit -m "feat: добавить валидацию"
# ✔ All good!

Commitizen — интерактивный помощник

npm install -D commitizen cz-conventional-changelog

# Добавить в package.json:
# "config": { "commitizen": { "path": "cz-conventional-changelog" } }

# Использование
npx cz
# или
git cz

# ? Select the type of change: feat
# ? What is the scope: auth
# ? Short description: добавить OAuth
# → feat(auth): добавить OAuth

semantic-release — автоматические релизы

npm install -D semantic-release

# .releaserc.json()
{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/github"
  ]
}

Как работает:

fix: ...  → PATCH релиз (1.0.1)
feat: ... → MINOR релиз (1.1.0)
feat!: .. → MAJOR релиз (2.0.0)

Генерация CHANGELOG

Из conventional commits автоматически генерируется:

# Changelog

## [1.3.0] - 2026-04-06
### Features
- **auth**: добавить OAuth через Google (#42)
- **search**: добавить поиск по каталогу (#45)

### Bug Fixes
- **ui**: исправить отображение на мобильных (#43)
- **api**: исправить таймаут при загрузке файлов (#44)

Частые ошибки

  • Тип не соответствует изменениям — feat для исправления бага
  • Описание на английском в русскоязычном проекте — команда должна договориться о языке
  • Scope слишком общий — fix(app): ... не несёт информации
  • Одним коммитом feat + fix — разделяйте на два коммита
  • Не использовать BREAKING CHANGE — при изменении API обязательно помечать

Практика

  1. Сделайте 10 коммитов с разными типами: feat, fix, docs, refactor, test
  2. Установите commitlint и попробуйте отправить некорректный коммит
  3. Установите commitizen и создайте коммит через интерактивный режим
  4. Настройте husky + commitlint для автоматической проверки

Связанные темы

Ресурсы