[Программирование, Git, Софт] Учимся писать информативные комментарии к GIT-коммитам используя общепринятую семантику (перевод)
Автор
Сообщение
news_bot ®
Стаж: 6 лет 9 месяцев
Сообщений: 27286
Когда я только знакомился с системами контроля версий (особенно с 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
===========Похожие новости:
- [PHP, JavaScript, Программирование] OpenCart popup, модальные окна
- [Настройка Linux, DevOps, Kubernetes] Kubernetes или с чего начать, чтобы понять что это и зачем он нужен
- [Программирование, Системное программирование, Отладка, Реверс-инжиниринг] Особенности структурной обработки исключений в Win64
- [Программирование, Разработка мобильных приложений, Учебный процесс в IT, Карьера в IT-индустрии] 1 марта SimbirSoft приглашает на Весенний интенсив
- [Разработка веб-сайтов, PHP, Программирование] Это не легаси-код, это PHP (перевод)
- [Разработка веб-сайтов, JavaScript, Программирование] Будущее JavaScript: декораторы
- [Программирование микроконтроллеров, Разработка под Arduino, DIY или Сделай сам] Запускаем код для Arduino в браузере
- [Программирование, Машинное обучение] Введение: Соревнование от финансовой группы HOME CREDIT по определеню риска дефолта заемщика
- [Open source, PHP, PostgreSQL, Совершенный код, GitHub] Интеграция PHP проекта на GitHub и Scrutinizer
- [FPGA, Программирование микроконтроллеров, Учебный процесс в IT, Компьютерное железо, Робототехника] Passcode Data Protection by Using FPGA and Verilog
Теги для поиска: #_programmirovanie (Программирование), #_git, #_soft (Софт), #_developer, #_programming, #_productivity, #_blog_kompanii_otus._onlajnobrazovanie (
Блог компании OTUS. Онлайн-образование
), #_programmirovanie (
Программирование
), #_git, #_soft (
Софт
)
Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы
Текущее время: 22-Ноя 18:13
Часовой пояс: UTC + 5
| Автор | Сообщение |
|---|---|
|
news_bot ®
Стаж: 6 лет 9 месяцев |
|
 Когда я только знакомился с системами контроля версий (особенно с 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] Автоматическое размещение виджета поиска
<type>(<опциональная область>): <описание изменения>
<пустая линия> [необязательное тело] <пустая линия> [необязательный нижний колонтитул] feat: добавить колебание шапки
^ — ^ ^ — — — — — — ^ | | | +-> Резюме в настоящем времени. | + - - - -> Type: chore, docs, feat, fix, refactor, style или test.
refactor(FOW-1327): рефакторинг класса аутентификации
добавить новое имя класса `userRepo` и извлечь вызов api в `/api/v1/users/me` из аутентификации в отдельный класс и использовать новый класс для хранения всех внешних вызовов api, связанных с данными пользователя  Git-коммиты, отраженные в Jira.Другой пример с моей работы, который опирается на это соглашение, - это библиотека системы проектирования с открытым исходным кодом под названием Kaizen, где общепринятый формат коммитов (особенно fix и feat) используется для создания описаний в чейнджлогах релизов пакетов.ЗаключениеПосле того, как все это время я стремился улучшить способ написания комментариев к git-коммитам, я могу с уверенностью утверждать, что использование общепринятых коммитов помогло мне стать лучшим разработчиком. Теперь, когда я смотрю историю своего git-репозитория, я могу быстро выяснить, что произошло в репозитории за последнее время, и догадаться о сути изменений, просто посмотрев на комментарий к коммиту.Ссылки
=========== Источник: habr.com =========== =========== Автор оригинала: Martin David Valentino ===========Похожие новости:
Блог компании OTUS. Онлайн-образование ), #_programmirovanie ( Программирование ), #_git, #_soft ( Софт ) |
|
Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы
Текущее время: 22-Ноя 18:13
Часовой пояс: UTC + 5