Git – самая популярная система контроля версий: большинство разработчиков используют ее и для личных, и для командных проектов. При этом многие разработчики, особенно начинающие, небрежно подходят к выбору названий ветвей и оформлению коммитов. Это оставляет не лучшее впечатление об их профессионализме, но что еще хуже – затрудняет командную работу и усложняет поддержание кодовой базы. В этой статье мы разберем лучшие практики для работы с ветвями и коммитами.
Названия ветвей: рекомендации сообщества
Одна из самых важных практик при работе в системе версий – использование понятных и описательных имен для веток, коммитов, запросов на вытягивание и так далее. Описательныe названия:
- Помогают отслеживать историю изменений кода.
- Упрощают документирование процесса.
- Повышают эффективность работы.
Соблюдение соглашений, созданных сообществом, носит рекомендательный характер – никто не принуждает разработчиков соблюдать эти правила. Однако если вы попробуете следовать этим рекомендациям, то быстро заметите, что они действительно упрощают и ускоряют работу.
Итак, оптимальное название ветви соответствует этим критериям:
- Дает четкое и ясное представление о том, что именно делает содержащийся в ветви код.
- Написано в нижнем регистре. Верхний регистр и тем более капслок, как правило, не используют. Есть только одно исключение – когда в префиксе необходимо использовать номера задач из таск-менеджеров (об этом ниже).
- Состоит только из букв и цифр (a-z, 0-9), не содержит специальных символов.
- При необходимости разделено дефисами -. Если название состоит из нескольких слов, имеет смысл разделить их дефисами. Не следует использовать PascalCase, camelCase или snake_case.
- Не заканчивается дефисом. Поскольку дефис используется для разделения слов, нет смысла использовать его в конце названия.
- Не содержит повторяющихся дефисов --. Если нужно начать название с типа ветки (feature, bugfix, hotfix), используйте слэш / для отделения типа от основного названия.
Примеры корректных названий:
- feature/new-sidebar
- add-new-sidebar
- hotfix/interval-query-param-on-get-historical-data
Неправильные названия:
- fixSidebar
- feature-new-sidebar-
- FeatureNewSidebar
- feat_add_sidebar
Библиотека программиста
Больше полезных материалов вы найдете на нашем телеграм-канале «Библиотека программиста»
Рекомендации по префиксам
Иногда назначение ветви сложно определить по одному лишь названию. Чтобы явно указать назначение ветви (исправление бага, новая функциональность, обновление документации и т.п.), принято использовать префиксы.
Вот общепринятые префиксы:
- feature – указывает на то, что в ветке разрабатывается новая фича, например feature/add-filters говорит о том, что в этой ветке идет работа по добавлению фильтров.
- release – используется для подготовки новых версий. Например, в ветке release/v3.3.1-beta делают последние правки и проверки перед выпуском новой версии: исправляют оставшиеся баги, обновляют документацию, меняют номер версии в коде и т.д. После того как подготовка завершена, содержимое ветки release сливают (merge) обратно в основную ветку. В результате в репозитории появляется новая версия кода со всеми изменениями из ветки release. Ее и выпускают как новый релиз.
- bugfix – применяется для исправления ошибок в коде. Обычно такая ветка создается при наличии конкретной проблемы (issue) с описанием найденного бага. Например, bugfix/sign-in-flow означает исправление ошибки в процессе входа в систему авторизации.
- hotfix – похож на bugfix, с одним важным отличием: hotfix используется для быстрого исправления критических багов, которые уже попали в продакшен. Например, hotfix/cors-error означает исправление срочной ошибки CORS, связанной с междоменными запросами, которая сломала работу приложения в продакшене.
- docs – обозначает ветку, предназначенную для написания документации к проекту. Например, docs/quick-start – это ветка для написания инструкции по быстрому запуску проекта.
Использование номеров задач в префиксах
Многие команды используют системы трекинга задач – Jira, Trello, ClickUp и т.д. В этих таск-менеджерах каждая задача получает уникальный номер, например T-142. Чтобы увязать работу в Git с этими задачами, в имени ветки указывают ее номер в неизменном виде. Например:
- feature/T-531-add-sidebar – ветка для новой фичи, описанной в задаче T-531
- docs/T-789-update-readme – обновление документации по задаче T-789
- hotfix/T-142-security-path – исправление уязвимости в продакшене из задачи T-142
Такой подход позволяет синхронизировать работу в Git с общим планированием и отслеживанием прогресса всей команды в системе задач: менеджер сразу видит, какая ветка соответствует какой задаче из общего плана.
Статья по теме
⚙️ 3 совета по использованию Git для начинающих
Рекомендации по написанию коммитов
На GitHub очень часто встречаются проекты с комментариями, которые понятны только их автору, типа «добавил много классных фич». Между тем, информативные комментарии к коммитам помогают создать четкую, наглядную историю изменений, которая сильно облегчает задачу поддержания кодовой базы.
Сообщение коммита состоит из трех частей – темы, описания и футера:
- Тема коммита обязательна и определяет его цель.
- Описание используется для дополнительного контекста и объяснения.
- Футер («подвал») обычно содержит метаданные – например, номер задачи.
Использование описания и подвала считается хорошей практикой, но не обязательно.
При написании коммитов рекомендуется следовать перечисленным ниже правилам.
Используйте повелительное наклонение
Императив подчеркивает цель и суть изменений в коде:
- Add README.md ✅
- Fix login bug ✅
- Update dependencies ✅
Не пишите комментарии в прошедшем и длительном временах:
- Added README.md ❌
- Adding README.md ❌
Начинайте комментарий с заглавной буквы
- Add user authentication ✅
- add user authentication ❌
Точка не нужна
- Update unit tests ✅
- Update unit tests. ❌
Дополнительные рекомендации
- Тема коммита должна быть ясной и понятной. Рекомендуемая длина текста – не более 50 символов.
- Описание (тело коммита) отделяется от темы пустой строкой. Текст описания должен укладываться в 72 символа.
- Для разделения текста описания на параграфы используют пустые строки.
- Помимо параграфов, можно использовать маркированные списки.
Статья по теме
🔶 Гайд по работе с деревом коммитов Git для начинающих
Спецификация Conventional Commits
Conventional Commits – соглашение по написанию информативных сообщений коммитов. Соблюдение этого набора правил помогает создать понятную, наглядную историю изменений кодовой базы.
Структура
Сообщение коммита по спецификации Conventional Commits имеет следующую структуру:
- type – тип
- scope – область
- description – описание
- footer(s) – подвал(ы)
Тип коммита
Tип – первая часть сообщения коммита. Он четко указывает на категорию действий, выполненных в этом коммите.
Список типов:
- feat – добавление новой функциональности
- fix – исправление ошибок
- refactor – изменение кода без изменения функциональности
- chore – вспомогательные изменения (конфиги, скрипты)
- docs – изменение документации
- perf – оптимизация производительности
- style – изменение стиля кода
- test – добавление или исправление тестов
- build – изменение системы сборки
- ci – изменение конфигурации CI
- env – изменение файлов окружения CI
Область
После типа коммита можно указать область – то есть дополнительную контекстную информацию:
- fix(ui): resolve issue with button alignment (исправлена проблема с выравниванием кнопки)
- feat(auth): implement user authentication (реализована аутентификация пользователей)
Тело
Тело сообщения предоставляет подробное описание изменений. Обычно идет после пустой строки после заголовка.
Пример:
Подвал
В подвале указывается дополнительная информация о коммите – кто проверил, одобрил и т.д.
Пример:
Изменение обратной совместимости
Можно указать, что коммит вносит значительные изменения, которые могут повлиять на совместимость: добавить BREAKING CHANGE в подвал или ! после типа и области.
Пример:
А это пример полного сообщения – с типом, описанием и подвалом:
Подведем итоги
Следование изложенным выше рекомендациям по написанию сообщений коммитов и наименованию ветвей важно для поддержания любых проектов, особенно крупных. Информативные сообщения и названия веток улучшают читаемость истории изменений репозитория, облегчают понимание кода для новых участников команды, упрощают ревью, откат ошибок и поиск нужных изменений.
***
При написании статьи использовалась публикация Be a better developer with these Git good practices.