Перейти к основному содержимому

Написание сообщений в Git

Данный документ содержит общие рекомендации по написанию сообщений при фиксации изменений в Git.
Эти рекомендации составлены на основе общеизвестных практик, а также личном опыте командной работы и автоматизации.

примечание
  • Тема — это первая строка комментария, краткое описание.
  • Тело — последующие строки, которые могут содержать более детальную информацию.

Включать номер задачи в тему сообщения​

  • Это поможет автоматизировать процесс фиксации и анализа выполненной работы по задаче.
  • Это поможет найти задачу и понять, что происходило, когда возникнет такая необходимость. В больших проектах и при командной работе это случается чаще, чем может казаться.
✔️ Хороший пример⛔ Плохой пример
JIRA-1725: Добавить файл README.mdДобавил файл README.md

Использовать повелительную форму в теме сообщения​

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

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

✔️ Хороший пример⛔ Плохой пример
ISSUE-5217: Add CHANGELOG.mdISSUE-5217: Added CHANGELOG.md
ISSUE-5217: Обновить вызов внешнего сервисаISSUE-5217: Обновил вызов внешнего сервиса
ISSUE-5217: Удалить аргументы из метода FooISSUE-5217: Удалил аргументы из метода Foo

Не ставить точку в теме сообщения​

Первая строчка комментария не должна заканчиваться точкой. Это тема сообщения. Тема не может заканчиваться точкой.

✔️ Хороший пример⛔ Плохой пример
EXMPL-1925: Добавить метод загрузкиEXMPL-1925: Добавить метод загрузки.

Тема должна быть максимально короткой и информативной​

Первая строка комментария фиксации должна быть максимально короткой.

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

Это необходимо для удобства и скорости просмотра истории. Причем удобство будет как при просмотре через интерфейс командной строки, так и в клиентах с графическим интерфейсом.

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

✔️ Хороший пример⛔ Плохой пример
MYLLM-7841: Добавить конфигурацию клиента MCPMYLLM-7841: Добавить в настройки адрес, порт и токен для подключения к серверу MCP

Разделять тему и тело сообщения пустой строкой​

Если комментарий многострочный, то между темой и телом следует разместить пустую строку.

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

✔️ Хороший пример⛔ Плохой пример
DATA-2078: Удалить таблицу Users

Заказчик против хранения пользователей в базе. Теперь мы будем использовать внешнее облачное хранилище.		DATA-2078: Удалить таблицу Users
Заказчик против хранения пользователей в базе. Теперь мы будем использовать внешнее облачное хранилище.

Тело должно отвечать на вопрос "зачем всё это было сделано"​

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

✔️ Хороший пример⛔ Плохой пример
AWESOME-2356: Добавить аргумент exclude

Это позволит исключать не нужные данные из выборки.		AWESOME-2356: Добавить аргумент exclude

Изменить логику функции. Небольшой рефакторинг.

Разнообразие​

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

✔️ Хороший пример⛔ Плохой пример
MYPROJECT-2518: Создать сервис отправки сообщенийMYPROJECT-2518: Реализация сервиса отправки сообщений
MYPROJECT-2518: Создать тесты для сервиса отправки сообщенийMYPROJECT-2518: Реализация сервиса отправки сообщений