Когда я только знакомился с системами контроля версий (особенно с 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-коммитам лучше (рекомендую вам прочитать всю статью, чтобы лучше разобраться в деталях по каждому из правил):

1. Отделяйте заголовок от тела пустой строкой

2. Ограничивайте заголовок 50 символами

3. Пишите заголовок с заглавной буквы

4. Не ставьте точку в конце заголовка

5. Используйте повелительное наклонение в заголовке

6. Переходите на следующую строку в теле на 72 символах

7. В теле отвечайте на вопросы что и почему, а не как

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

Общепринятые коммиты спешат на помощь

Так я мучался, пока мой коллега не показал мне это соглашение, называемое [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-репозитория, я могу быстро выяснить, что произошло в репозитории за последнее время, и догадаться о сути изменений, просто посмотрев на комментарий к коммиту.

Ссылки

• conventionalcommits

• Как писать следует писать комментарии к Git-коммитам, Крис Бимс

• Искусство коммита, Дэвид Демари

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