[Перевод] Учимся писать информативные комментарии к GIT-коммитам используя общепринятую семантику
Когда я только знакомился с системами контроля версий (особенно с 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”, а таже записаться на день открытых дверей.