⚙️ Названия ветвей и комментарии к коммитам в 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 с общим планированием и отслеживанием прогресса всей команды в системе задач: менеджер сразу видит, какая ветка соответствует какой задаче из общего плана.

Рекомендации по написанию коммитов

На 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 символа.
• Для разделения текста описания на параграфы используют пустые строки.
• Помимо параграфов, можно использовать маркированные списки.

Спецификация Conventional Commits

Conventional Commits – соглашение по написанию информативных сообщений коммитов. Соблюдение этого набора правил помогает создать понятную, наглядную историю изменений кодовой базы.

Структура

Сообщение коммита по спецификации Conventional Commits имеет следующую структуру:

• type – тип
• scope – область
• description – описание
• footer(s) – подвал(ы)

        <type>[optional scope]: <description>

[optional body]

[optional 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 (реализована аутентификация пользователей)
  

Тело

Тело сообщения предоставляет подробное описание изменений. Обычно идет после пустой строки после заголовка.

Пример:

        Add new functionality to handle user authentication.

This commit introduces a new module to manage user authentication. It includes
functions for user login, registration, and password recovery.
    

        Добавлена функция обработки аутентификации.

Добавлен новый модуль для управления аутентификацией пользователей.
Включает функции для входа, регистрации пользователей и восстановления пароля.
    

Подвал

В подвале указывается дополнительная информация о коммите – кто проверил, одобрил и т.д.

Пример:

        Signed-off-by: John <john.doe@example.com> // Подписано
Reviewed-by: Anthony <anthony@example.com> // Проверено
    

Изменение обратной совместимости

Можно указать, что коммит вносит значительные изменения, которые могут повлиять на совместимость: добавить BREAKING CHANGE в подвал или ! после типа и области.

Пример:

        chore: add commitlint and husky
chore(eslint): enforce the use of double quotes in JSX
refactor: type refactoring
feat: add axios and data handling
feat(page/home): create next routing
chore!: drop support for Node 18
    

        chore: добавлены commitlint и husky
chore(eslint): принудительное использование двойных кавычек в JSX
refactor: рефакторинг типов 
feat: добавлен axios и обработка данных
feat(page/home): создано маршрутизирование  
chore!: прекращена поддержка Node 18
    

А это пример полного сообщения – с типом, описанием и подвалом:

        feat: add function to convert colors in hexadecimal to rgba

Lorem Ipsum is simply dummy text of the printing and typesetting industry.

Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.

Reviewed-by: 2
Refs: #345
    

        feat: добавлена функция конвертации цветов из HEX в RGBA

Lorem Ipsum - это стандартный текст-«рыба», используемый в печати и веб-дизайне.

Lorem Ipsum является стандартной «рыбой» для текстов на латинице с начала XVI века.

Reviewed-by: 2
Refs: #345
    

Подведем итоги

Следование изложенным выше рекомендациям по написанию сообщений коммитов и наименованию ветвей важно для поддержания любых проектов, особенно крупных. Информативные сообщения и названия веток улучшают читаемость истории изменений репозитория, облегчают понимание кода для новых участников команды, упрощают ревью, откат ошибок и поиск нужных изменений.

При написании статьи использовалась публикация Be a better developer with these Git good practices.