Наименование коммитов по стандарту Conventional Commits

Git — это популярная система контроля версий, которая позволяет разработчикам отслеживать изменения в коде и управлять историей проекта. Одним из ключевых аспектов работы с Git является создание коммитов. Правильное оформление коммитов помогает улучшить читаемость истории проекта, облегчает понимание изменений и упрощает совместную работу. В этой статье мы рассмотрим, как правильно делать коммиты в Git, с особым акцентом на структуру сообщений и типы изменений.

Чем хорош Conventional Commits

Помимо Conventional Commits, существует множество вариантов оформления коммитов, например, Gitmoji — используются информативные эмодзи.

Хотя использование эмодзи является интересным вариантом, я предпочитаю Conventional Commits по следующим причинам:

• Информативность.
• Понятность.
• Простота.
• Популярность.
• Наличие подробной спецификации с примерами и ответами на вопросы.

Conventional Commits — это способ писать сообщения о том, что мы изменили в коде, так, чтобы они были понятными и простыми. Это помогает всем в команде быстро понимать, что было сделано, и автоматически создавать списки изменений. Такой подход делает работу над проектом легче и лучше.

Структура коммита

Согласно документации, сообщение о коммите должно быть структурировано следующим образом:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Сосредоточимся только на обязательных частях, которых всего две:

1. type — тип изменения;
2. description — краткое описание.

Общие рекомендации по написанию сообщений коммитов

• Используйте повелительное наклонение: формулируйте сообщения как команды, например, «добавить», «исправить», «удалить».
• Будьте краткими, но информативными: сообщения должны быть понятными и конкретными, избегайте излишней общей информации.
• Избегайте использования «я»: например, вместо «я добавил» пишите «добавить».
• Следуйте единому стилю: если в команде уже принят определенный стиль сообщений, следуйте ему для единообразия.

Тип изменения (type) и краткое описание (description)

Тип изменения (feat, fix и т.д.) — это первая часть сообщения коммита, которая помогает быстро понять, какое именно изменение было внесено.

Краткое описание должно быть лаконичным и четким, обычно не превышает 50 символов. Оно должно начинаться с маленькой буквы и описывать суть изменений.

Ниже перечислены основные типы и приведены примеры с кратким описанием.

В примерах использован русский язык, но на практике разумно применять английский, что обеспечит понимание для более широкой аудитории.

feat — сообщает о добавлении нового функционала. Это может быть новая функция или улучшение существующей функциональности.

git commit -m 'feat: добавить функцию поиска по пользователям'
git commit -m 'feat: интегрировать API для получения данных о погоде'
git commit -m 'feat: создать компонент для отображения карточек товаров'

fix — используется для обозначения исправления ошибок. Это включает в себя любые изменения, которые устраняют баги.

git commit -m 'fix: исправить ошибку 500 при запросе к /users'
git commit -m 'fix: устранить проблему с отображением кнопки Сохранить'
git commit -m 'fix: исправить сбой при входе с неправильным паролем'

docs — изменения в документации. Это может быть обновление README, добавление комментариев или улучшение документации API.

git commit -m 'docs: обновить документацию по установке'
git commit -m 'docs: исправить опечатки в README.md'
git commit -m 'docs: добавить лицензию проекта'

style — охватывает изменения, не влияющие на логику программы, такие как форматирование кода, пробелы или изменения в стиле.

git commit -m 'style: удалить лишние пробелы в коде'
git commit -m 'style: изменить шрифт заголовков для соответствия дизайну'
git commit -m 'style: добавить пробелы между функциями для улучшения читаемости'

refactor — подразумевает изменения в коде, которые не добавляют функциональности и не исправляют ошибки, но улучшают структуру или читаемость кода.

git commit -m 'refactor: переименовать переменные для лучшей читаемости'
git commit -m 'refactor: упростить функцию валидации формы'
git commit -m 'refactor: выделить общий код в отдельный метод'

perf — для изменений, которые улучшают производительность приложения.

git commit -m 'perf: уменьшить время загрузки страницы'
git commit -m 'perf: оптимизировать алгоритм сортировки'
git commit -m 'perf: кэшировать результаты API'

test — добавление или изменение тестов. Это может быть написание новых тестов или исправление существующих.

git commit -m 'test: добавить юнит-тесты для функции валидации'
git commit -m 'test: оптимизировать алгоритм сортировки'
git commit -m 'test: кэшировать результаты API'

build — относится к изменениям, касающимся системы сборки или внешних зависимостей (например, изменения в конфигурации Webpack, обновление библиотек и т.д.).

git commit -m 'build: обновить зависимости до новых версий'
git commit -m 'build: добавить плагин для минификации CSS'
git commit -m 'build: удалить устаревшие скрипты сборки'

ci — охватывает изменения в конфигурации CI/CD (непрерывной интеграции и доставки).

git commit -m 'ci: обновить конфигурацию Travis CI'
git commit -m 'ci: добавить этап сборки в конвейер CI'
git commit -m 'ci: исправить ошибки в конфигурации CircleCI'

chore — включает изменения, которые не попадают в другие категории, например, обновления задач, настроек и других мелочей.

git commit -m 'chore: очистить старые ветки в репозитории'
git commit -m 'chore: обновить ссылку на email'
git commit -m 'chore: добавить значок загрузки'

revert — используется для отмены предыдущего коммита. Это позволяет легко вернуть изменения, если они были ошибочными.

git commit -m 'revert: вернуть изменения в "docs: обновить документацию по API"'
git commit -m 'revert: отменить коммит "feat: добавить функцию аутентификации"'
git commit -m 'revert: вернуть изменения в "fix: исправить ошибку в функции расчета"'

Стандарт Conventional Commits используют многие крупные команды, например, разработчики популярного фреймворка Vue.js. Репозиторий доступен по адресу https://github.com/vuejs.

Каждый тип коммита может быть дополнен дополнительной информацией, такой как область и описание, что помогает лучше понять суть изменений. Стандарт Conventional Commits способствует улучшению управления версиями и упрощает процесс работы с кодом.

Необязательные элементы: scope, body, footer(s)

• scope (область видимости) — МОЖЕТ быть указана после типа. ДОЛЖНА состоять из существительного, описывающего раздел кодовой базы, заключённого в скобки, например, fix(parser).
• body — после краткого описания МОЖЕТ быть добавлен более длинный текст коммита, содержащий дополнительную контекстную информацию об изменениях в коде. Текст коммита ДОЛЖЕН начинаться с пустой строки после описания.
• footer — МОЖЕТ использоваться для добавления дополнительной информации. Обычно футер используется для указания ссылок на задачи или баги, связанные с коммитом, а также для указания о том, что данный коммит закрывает определенные задачи.

Ниже пример коммита с GitHub Angular:

refactor(docs-infra): complete removal of aio directory (#56496)

Finish removal of aio directory as it is no longer used or relied upon.

PR Close #56496

Видео от основателя JavaScript.ru Ильи Кантора

Очень важно, чтобы каждый коммит делал только одну вещь. Например, коммит исправляющий ошибку, или коммит добавляющий какой-то функционал. Это свойство называют атомарностью (atomic) и поэтому коммиты, как правило, небольшие. Реализовали что-то, посмотрели, убедились, что работает, добавили в индекс, закоммитили.

Заключение

Правильное оформление коммитов в Git — это важный аспект разработки, который помогает поддерживать чистоту и понятность истории изменений в проекте. Используя четкие типы изменений, лаконичные описания и дополнительную информацию, вы сделаете вашу работу более понятной для себя и других участников команды. Следуя рекомендациям выше, вы сможете значительно упростить процесс совместной работы и улучшить качество документации проекта.