[Программирование, Git, Софт] Учимся писать информативные комментарии к GIT-коммитам используя общепринятую семантику (перевод)

Автор Сообщение
news_bot ®

Стаж: 6 лет 3 месяца
Сообщений: 27286

Создавать темы news_bot ® написал(а)
13-Янв-2021 19:30


Когда я только знакомился с системами контроля версий (особенно с 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 это также будет отражено.
Git-коммиты, отраженные в Jira.Другой пример с моей работы, который опирается на это соглашение, - это библиотека системы проектирования с открытым исходным кодом под названием Kaizen, где общепринятый формат коммитов (особенно fix и feat) используется для создания описаний в чейнджлогах релизов пакетов.ЗаключениеПосле того, как все это время я стремился улучшить способ написания комментариев к git-коммитам, я могу с уверенностью утверждать, что использование общепринятых коммитов помогло мне стать лучшим разработчиком. Теперь, когда я смотрю историю своего git-репозитория, я могу быстро выяснить, что произошло в репозитории за последнее время, и догадаться о сути изменений, просто посмотрев на комментарий к коммиту.Ссылки А прямо сейчас приглашаем ва ознакомиться с программой супер-интенсива "Версионирование и командная работа с помощью Git", а таже записаться на день открытых дверей.
===========
Источник:
habr.com
===========

===========
Автор оригинала: Martin David Valentino
===========
Похожие новости: Теги для поиска: #_programmirovanie (Программирование), #_git, #_soft (Софт), #_developer, #_programming, #_productivity, #_blog_kompanii_otus._onlajnobrazovanie (
Блог компании OTUS. Онлайн-образование
)
, #_programmirovanie (
Программирование
)
, #_git, #_soft (
Софт
)
Профиль  ЛС 
Показать сообщения:     

Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы

Текущее время: 15-Май 17:12
Часовой пояс: UTC + 5