Лучшие практики для сообщений фиксаций

Представьте, что Вы просматриваете историю проекта. Без понятных сообщений коммитов это всё равно что читать дневник с пустыми записями!

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

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

• Тема: одна краткая строка с описанием изменения.
• Текст: необязательное более подробное объяснение, отделённое от темы пустой строкой.

Представьте это как электронное письмо: тема позволяет быстро понять содержание, а текст содержит подробности.

Тема — самая важная часть сообщения. Соблюдайте следующие правила:

• Краткость: не более 50–72 символов.
• Повелительное наклонение: начинайте с глагола в настоящем времени (например, «Добавить возможность», а не «Добавлена возможность» или «Добавление возможности»).
• Прописная первая буква: это стандартная практика, улучшающая читаемость.
• Без точки: не заканчивайте тему точкой.

Рассмотрим удачные и неудачные темы:

• Удачная: Fix: broken login button
• Удачная: Feat: implement user profile page
• Неудачная: Fixed a bug in the login system that was causing issues. (слишком длинная, прошедшее время)
• Неудачная: updates (слишком расплывчатая)

Стремитесь к ясности и краткости!

В тексте коммита объясняются мотивы изменения, его контекст и любые подробности, которые не очевидны из самого кода.

Используйте текст, когда изменение требует более подробного объяснения, чем может вместить тема. Для удобства чтения в инструментах Git ограничивайте длину строк примерно 72 символами.

При написании текста:

• Объясняйте, почему было внесено изменение, а не только что изменилось.
• Описывайте компромиссы и решения по проектированию.
• Упоминайте возможные побочные эффекты и области, требующие внимания.
• Оставляйте пустую строку между темой и текстом.

Это предоставляет ценный контекст будущим читателям.

Полное хорошо структурированное сообщение коммита может выглядеть так:

Многие команды используют соглашение, согласно которому тема начинается с префикса типа. Это помогает быстро распределять изменения по категориям.

Распространённые префиксы:

• feat: (новая возможность)
• fix: (исправление ошибки)
• docs: (изменение документации)
• style: (стиль кода без функциональных изменений)
• refactor: (переработка кода)
• test: (добавление тестов)
• chore: (обслуживание и изменения процесса сборки)

Хорошей практикой считается связывать коммиты с соответствующими задачами или запросами на включение изменений в системе управления проектом (например, GitHub Issues или Jira).

Для этого обычно в текст сообщения коммита добавляют фразы Closes #123, Fixes #45 или Refs #67. Это автоматически связывает изменения кода с отслеживаемой задачей.

Какие из перечисленных характеристик соответствуют хорошо составленному сообщению коммита Git согласно лучшим практикам?

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

• Пишите краткие темы в повелительном наклонении.
• Используйте текст, чтобы объяснить, «почему» было внесено изменение.
• Рассмотрите возможность использования префиксов типов для категоризации.
• Добавляйте ссылки на задачи или запросы на включение изменений, чтобы предоставить контекст.

Удачных коммитов!