Когда я только знакомился с системами контроля версий (особенно с git), я рассматривал их только как приложения, которые помогают мне хранить историю изменений моего кода. Т.е. когда случается что-то нехорошее, я могу просмотреть историю коммитов и вернуться к последнему «хорошему» состоянию кода в моем репозитории.
Но когда я начал более плотно использовать их в своей работе, я понял, что их функция шире, чем просто контроль версий, это также инструмент совместной работы, где вы описываете свою историю взаимодействия с репозиторием и делитесь ею с другими разработчиками. Именно тогда я узнал, что хорошие комментарии к коммитам (commit message) могут значительно улучшить ваше взаимодействие с другими членами команды (и не только).
В этой статье я расскажу о том, как хороший стиль написания комментариев к коммитам может помочь вам стать лучшим разработчиком, и как общепринятые коммиты (conventional commits - соглашение о семантике комментариев к коммитам, которое я использую и рекомендую вам) упростят и улучшат ваш процесс написания комментариев к коммитам.
Ранние годы
В ранние годы использования git я никогда особо не заморачивался о том, как писать комментарии к коммитам. Большая часть моих комментариев к коммитам выглядела следующим образом:
commit e71fcf2022b6135e18777bdc58c2ac3180202ec7
Author: mvalentino
Date: Tue Apr 24 01:25:48 2015 +1000
Извлечение информации для страницы оплаты
commit d1952883b05b685f2d22e4c41b4fbc4362fd6bd0
Author: mvalentino
Date: Mon Apr 23 22:16:50 2015 +1000
[WIP] Интеграция полосы
commit 74b8920d96e3e09d5cd958ffa369a0e3c86a6851
Author: mvalentino
Date: Mon Apr 23 21:09:11 2015 +1000
Генерация ссылки для платежа
commit b02255b25eed57c7595504c66233d5ee3024190c
Author: mvalentino
Date: Mon Apr 23 18:32:40 2015 +1000
[WIP] Автоматическое размещение виджета поиска
У меня не возникало даже мысли использовать тело коммита. Моей дежурной командой неизменно служила git commit -m <commit message>
. Когда вы работаете в компании, которая занимается пиаром, код ревью не является для вас привычной практикой. Никто даже не думал предложить мне обратить внимание на мои комментарии к коммитам. Ситуация изменилась, когда я перешел в компанию с хорошей инженерной культурой, где я научился написанию комментариев, четко объясняющих, что это за коммит, как неотъемлемой части моей работы.
Пытаясь найти лучший способ писать комментарии к коммитам, я наткнулся на эту статью от разработчика по имени Крис Бимс. В этой статье я впервые увидел термин «атомарный коммит». Из этой статьи я узнал 7 правил, которые помогут вам сделать ваши комментарии к git-коммитам лучше (рекомендую вам прочитать всю статью, чтобы лучше разобраться в деталях по каждому из правил):
Отделяйте заголовок от тела пустой строкой
Ограничивайте заголовок 50 символами
Пишите заголовок с заглавной буквы
Не ставьте точку в конце заголовка
Используйте повелительное наклонение в заголовке
Переходите на следующую строку в теле на 72 символах
В теле отвечайте на вопросы что и почему, а не как
Перенесемся на два месяца назад - я, насмотревшись комментариев к коммитам других разработчиков, чтобы использовать их в качестве примеров для структурирования моих собственных комментариев, продолжаю пытаться применять правила, указанные выше. Одна вещь, которая мешает мне написать хороший комментарий к коммиту, - это неспособность определить, какие изменения относятся к какому комментарию. Каждый раз, когда я хочу закоммитить свои изменения, у меня запускается мысленный процесс, пытающийся разделить изменения, чтобы их можно было сгруппировать как можно более «атомарно».
Общепринятые коммиты спешат на помощь
Так я мучался, пока мой коллега не показал мне это соглашение, называемое [conventional commits] (общепринятые коммиты - https://www.conventionalcommits.org/ru/v1.0.0-beta.2/), которое значительно облегчило написание четких и ясных комментариев к коммитам. Оно в первую очередь определяет набор структур, чтобы вы знали, какие изменения относятся к какому типу комментария.
В общепринятых коммитах есть 16 спецификаций, которые определяют, каким должен быть комментарий к коммиту. Я могу не помнить досконально всех спецификаций, но в целом я всегда стараюсь следовать основному соглашению, которое определяет структуру заголовка комментария к коммиту.
Вкратце, для каждого комментария к коммиту структура всегда следующая
<type>(<опциональная область>): <описание изменения>
<пустая строка>
[необязательное тело]
<пустая строка>
[необязательный нижний колонтитул]
Первая строка комментария к коммиту будет иметь вид:
feat: добавить колебание шапки
^ — ^ ^ — — — — — — ^
| |
| +-> Резюме в настоящем времени.
|
+ - - - -> Type: chore, docs, feat, fix, refactor, style или test.
где <type>
может быть одним из следующих:
feat:
(новая фича для пользователя, а не, например, новая функция для скрипта сборки)
fix:
(исправление ошибки для пользователей, а не исправление скрипта сборки)
docs:
(изменения в документации)
style:
(форматирование, отсутствующие точки с запятой и т. д .; без изменения производственного кода)
refactor:
(рефакторинг производственного кода, например, переименование переменной)
test:
(добавление недостающих тестов, рефакторинг тестов; без изменения производственного кода)
chore:
(обновление рутинных задач и т. д.; без изменения производственного кода).
Теперь я могу быстро определить, какие изменения я внес и как будет выглядеть комментарий к коммиту этих изменений. С этим форматом вы как разработчик можете сразу узнать (или хотя бы догадаться), что изменилось в конкретном коммите. Если возникла проблема с новым мержем с основной веткой, вы также можете быстро просмотреть историю git, чтобы выяснить, какие изменения могли вызвать проблему, без необходимости вникать в diff.
Как указано на сайте общепринятых коммитов, есть несколько веских причин использовать это соглашение.
Автоматическая генерация чейнджлогов.
Автоматическое определение семантического повышения версии (на основе типов совершенных коммитов).
Информирование товарищей по команде, сообщества и других заинтересованных сторон о характере изменений.
Запуск процессов сборки и публикации по триггерам.
Возможность упростить людям участие в ваших проектах, позволив им изучить более структурированную историю коммитов.
Как я использую это на практике
Для управления проектами в своей работе я использую Jira, и он также имеет интеграцию с Github. Недавно я узнал, что если вы укажете номер тикета Jira в комментарии к своему коммиту, Jira сможет автоматически обнаружить его и встроить непосредственно в карточку, над которой вы сейчас работаете в Jira. Это хорошо согласуется с соглашением, поскольку я могу указать номер тикета Jira как часть <optional scope>
в комментарии. Итак, теперь каждый раз, когда я работаю над задачей из Jira, мой комментарий к коммиту будет будет выглядеть
<type>(<номер тикета jira>): Название коммита
Пример из одного из комментариев к коммиту, который я недавно сделал
refactor(FOW-1327): рефакторинг класса аутентификации
добавить новое имя класса `userRepo` и извлечь вызов api в `/api/v1/users/me` из аутентификации в отдельный класс и использовать новый класс для хранения всех внешних вызовов api, связанных с данными пользователя
и в Jira это также будет отражено.
Другой пример с моей работы, который опирается на это соглашение, - это библиотека системы проектирования с открытым исходным кодом под названием Kaizen, где общепринятый формат коммитов (особенно fix
и feat
) используется для создания описаний в чейнджлогах релизов пакетов.
Заключение
После того, как все это время я стремился улучшить способ написания комментариев к git-коммитам, я могу с уверенностью утверждать, что использование общепринятых коммитов помогло мне стать лучшим разработчиком. Теперь, когда я смотрю историю своего git-репозитория, я могу быстро выяснить, что произошло в репозитории за последнее время, и догадаться о сути изменений, просто посмотрев на комментарий к коммиту.
Ссылки
Искусство коммита, Дэвид Демари
А прямо сейчас приглашаем ва ознакомиться с программой супер-интенсива "Версионирование и командная работа с помощью Git", а таже записаться на день открытых дверей.