Создание отличных сообщений коммитов Git: лучшие практики для чистой истории

Сообщения коммитов Git — это заметки, на которые полагается ваша команда, когда код ломается, поведение меняется или требуется объяснить релиз. Четкое сообщение говорит вам, что изменилось и почему, не заставляя вас обратно инженерить diff.

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

Почему важны хорошие сообщения коммитов?

Хорошие сообщения коммитов помогают несколькими практическими способами:

Понимание изменений: Они обеспечивают немедленный контекст того, что конкретный коммит вводит или изменяет, экономя время при просмотре кода или вспоминании прошлых решений.
Отладка: При отслеживании ошибок четкая история коммитов позволяет точно определить, когда и почему было внесено проблемное изменение.
Совместная работа: Для членов команды, присоединяющихся к проекту или возвращающихся к старому коду, хорошо написанные сообщения облегчают понимание траектории развития проекта.
Ревью кода: Они дают рецензентам представление о намерениях, стоящих за изменениями, способствуя более продуктивной и целенаправленной обратной связи.
Автоматизированные инструменты: Многие инструменты Git, такие как генераторы журналов изменений и создатели заметок к релизу, полагаются на сообщения коммитов для эффективной работы.
Историческая запись: Они служат формой документации, сохраняя эволюцию кодовой базы с течением времени.

Анатомия отличного сообщения коммита Git

Общепризнанная структура сообщений коммитов Git следует простому, но мощному шаблону: лаконичная тема, за которой следует необязательное, более подробное тело.

Тема

Тема — это первая строка вашего сообщения коммита. Это должно быть краткое, повелительное резюме изменений. Думайте об этом как о заголовке коммита.

Ключевые рекомендации для темы:

Будьте краткими: Около 50 символов — это полезная цель, а не жесткое ограничение. Держите тему достаточно короткой, чтобы ее можно было просмотреть в git log --oneline.
Используйте повелительное наклонение: Начинайте с глагола, описывающего действие, как если бы вы отдавали команду. Примеры: Fix, Add, Refactor, Update, Remove, Style.
Пишите первое слово с заглавной буквы: Стандартная конвенция предписывает писать первую букву темы с заглавной.
Не ставьте точку в конце: Тема — это заголовок, а не предложение.
Избегайте использования git commit -m "сообщение" для длинных сообщений: Хотя это удобно для коротких заметок, это может привести к менее структурированным сообщениям. Используйте git commit без аргументов, чтобы открыть редактор для более сложных сообщений.

Примеры хороших тем:

feat: add user authentication module
fix: resolve infinite loop in data processing
docs: update README installation steps
refactor: simplify image loading
chore: update development dependencies

Тело

Тело сообщения коммита — это место, где вы предоставляете больше контекста и деталей. Оно отделяется от темы пустой строкой. Этот раздел необязателен, но настоятельно рекомендуется для любых изменений, кроме тривиальных.

Ключевые рекомендации для тела:

Объясняйте «почему» и «как»: Не просто описывайте что изменилось; объясните, почему изменение было необходимо и как оно было реализовано. Какую проблему решает этот коммит? Каким было предыдущее поведение? Каково новое поведение?
Переносите строки на 72 символах: Это давняя конвенция, которая улучшает читаемость во многих инструментах Git и терминалах.
Используйте маркеры списка для перечислений: Если вам нужно перечислить несколько изменений или пунктов, используйте маркеры для ясности.
Ссылайтесь на задачи или тикеты: Если коммит относится к системе отслеживания задач (например, GitHub Issues, Jira), включите номер тикета для отслеживаемости.

Пример хорошего сообщения коммита (Тема + Тело):

feat: implement user profile page

This commit introduces the user profile page, allowing users to view and
edit their personal information.

Previously, users could not access or modify their profile details.
This change adds a new route (`/profile`) and a corresponding
component that fetches user data from the API and provides
forms for updating fields like name, email, and bio.

Related to #123.

Распространенные типы сообщений коммитов (Conventional Commits)

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

Conventional Commits используют префикс для обозначения типа изменения:

feat (функция): В кодовую базу вводится новая функция.
fix (исправление ошибки): Исправляется ошибка.
docs (документация): Изменения только в документации.
style (форматирование): Изменения, которые не влияют на смысл кода (пробелы, форматирование, отсутствующие точки с запятой и т.д.).
refactor (рефакторинг кода): Изменение кода, которое не исправляет ошибку и не добавляет функцию.
perf (производительность): Изменение кода, улучшающее производительность.
test (добавление недостающих тестов или исправление существующих): Добавление или исправление тестов.
build (изменения, влияющие на систему сборки или внешние зависимости): Примеры: npm-скрипты, webpack и т.д.
ci (изменения в файлах и скриптах конфигурации CI): Примеры: Travis, Circle, BrowserStack, SauceLabs и т.д.
chore (обслуживание): Задачи, которые не подходят под другие типы, например, ведение репозитория.

Область (необязательно): К префиксу может быть добавлена область, указывающая на затронутую часть кодовой базы. Например: feat(auth): Add JWT authentication.

Нижний колонтитул (необязательно): Используйте нижний колонтитул для ссылок на задачи, отметки критических изменений или добавления других метаданных. Conventional Commits использует BREAKING CHANGE: для критических изменений.

Пример использования Conventional Commits:

fix(api): correct endpoint for user data retrieval

Previously, the `/users/:id/data` endpoint returned outdated information.
This commit updates the endpoint to `/users/:id/profile` which fetches
the most current user profile data.

Closes #456

Советы по написанию отличных сообщений коммитов

Делайте коммиты часто, но логично: Делайте маленькие, атомарные коммиты, которые представляют одно логическое изменение. Это упрощает написание и понимание сообщений.
Пишите сообщения с точки зрения будущего проекта: Представьте, что вы смотрите на этот коммит через шесть месяцев. Какая информация вам понадобится, чтобы быстро понять изменение?
Будьте конкретны: Избегайте расплывчатых сообщений вроде "Update code" или "Bug fixes." Объясните точно, что было обновлено или исправлено.
Используйте обратные кавычки для ссылок на код: Если вы упоминаете имена файлов, функций или переменных, заключайте их в обратные кавычки (`).
Проверяйте свои сообщения: Перед коммитом найдите минутку, чтобы прочитать свое сообщение. Имеет ли оно смысл? Понятно ли оно?

Вывод

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