6.2 KiB
Правила оформления коммитов
Правила необходимы для предотвращения написания бессмысленных заголовков, мешающих пониманию ситуации на проекте. Хорошие оформленные коммиты помогают значительно облегчить процесс выяснения причин внесенных в код изменений, анализируя историю коммитов. Так же это необходимо для стилистического единообразия сообщений коммитов в репозитории.
Тексты сообщений коммитов
При написании сообщения коммита следует использовать формат:
#<НОМЕР ЗАДАЧИ> Короткое сообщение что сделано
Длинное сообщение что сделано
- Начинаем с номера задачи (например, #12311). Идентификатор необходим для интеграции с задачами GitHub
- В качестве разделителя между номером задачи и заголовком коммита используем пробел.
- Далее идет заголовок коммита:
- Пишем на русском языке.
- Заголовок с большой буквы.
- В конце заголовка точку не ставим.
- Желательно использовать настоящее время, а не прошедшее (например, "Исправление ошибок запуска при указанной web ИБ").
- Рекомендуем писать не слишком длинный заголовок, так как его отображение во многих интерфейсах выполнено в одну строку без переносов, так что, он может не влезть. Подробные детали пишем отдельным параграфом в описании коммита.
- Описание коммита (опционально).
- Отделяем от заголовка пустой строкой.
- Пишем полноценные предложения (начинаем с большой буквы, заканчиваем точкой)
- Хорошей практикой является ограничение длины строк в сообщении ≈72 символами, с добавлением переносов, если не влезает. Многие UI инструменты для GIT (в том числе EGit) не делают переносы текста описания, если он не влез.
Контент сообщения коммита:
В сообщении коммита пишем "что" и "почему" сделано, но избегаем деталей "как" сделано. Назначение комментария - дать коллегам понять, что происходит в проекте.
- Заголовок должен быть ёмкий и информативный.
- Заголовок должен быть написан официальным языком, без разговорных оборотов.
- Чтобы определить достаточность детализации заголовка коммита, попробуйте ответить на вопрос, не заглядывая в код:
[Bug]Какая конкретно проблема здесь исправлена?[Feature]Какая функциональность здесь добавлена?[Refactoring]В каких компонентах/классах произведен рефакторинг?[Tests]Что они тестируют?[Baseline]В каком компоненте/плагине/пакете подняли версию/версии?[docs]В каком компоненте добавлена документация?[fix]Какие именно проблемы вы исправили?
- Зачем писать сообщение коммита?
- Когда сделанные изменения неочевидны коллегам, то, помимо комментария в самом коде, не будет лишним описать детальнее, зачем эти изменения были сделаны или, почему сделаны именно так, а не иначе.
- При исправлении сложных багов можно воспользоваться методологией Root_cause_analysis, и указать причину ошибочного поведения, а так же каким образом это исправили. Человек (или даже вы сами), который через пару лет наткнется на неочевидное изменение, скажет вам спасибо.
Количество коммитов
Стоит ли делать один коммит на фичу - зависит от фичи. Коммит - логически завершенное изменение, а сложная фича может содержать много таких изменений, слияние которых в один коммит, приводит к потере информации о деталях ее выполнения. Это касается не только фич.
Squash'ить коммиты стоит, если были сделаны лишнее изменения, которые в следующих коммитах отменили. Так же, стоит избегать коммитов вида "Поднятие версий", которые не являются самостоятельными (вызваны другими изменениями, без них билд проекта не будет выполнен).