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

Семь правил отличного сообщения коммита Git

Имейте в виду: Это было все было сказано раньше.

  1. Отделите тему от тела пустой строкой
  2. Ограничьте строку темы до 50 символов
  3. Заглавная строка темы
  4. Не заканчивайте строку темы точкой
  5. Используйте повелительное наклонение в строке темы
  6. Оберните тело в 72 символа
  7. Используйте тело, чтобы объяснить что и почему по сравнению с как

1. Отделить тему от тела пустой строкой

Во-первых, не каждый коммит требует и темы, и тела. Иногда достаточно одной строки, особенно когда изменение настолько простое, что дополнительный контекст не требуется. Например:

Fix typo in introduction to user guide

Однако, когда фиксация заслуживает небольшого пояснения и контекста, вам нужно написать тело. Например:

Derezz the master control program
MCP turned out to be evil and had become intent on world domination.This commit throws Tron's disc into MCP (causing its deresolution) and turns it back into a chess game.
Avoid batch termination
In case the english horse name data is not present,error used to occur saying hash reference can't be done for undefined value. This fix checks the Variable to be Hash reference before performing other checks.

2. Ограничьте строку темы до 50 символов.

50 символов — это не жесткое ограничение, а просто эмпирическое правило. Сохранение строк темы такой длины гарантирует, что они удобочитаемы, и заставляет автора задуматься о наиболее кратком способе объяснить, что происходит.

Совет. Если вам сложно подвести итоги, возможно, вы вносите слишком много изменений одновременно. Стремитесь к атомарным коммитам.

Атомарный подход

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

Преимущества

  • Легко откатиться, не затрагивая другие изменения
  • Легко вносить другие изменения на лету
  • Легко объединять функции с другими ветвями

3. Используйте заглавную строку темы

Это так просто, как кажется. Начинайте все строки темы с заглавной буквы.

Например: fix indentation → Fix indentation

4. Не заканчивайте строку темы точкой

Знаки препинания в конце темы не нужны. Кроме того, пространство бесценно, когда вы пытаетесь уложиться в 50 символов или меньше.

Пример: Open the pod bay doors.→Open the pod bay doors

5. Используйте повелительное наклонение в строке темы

Повелительное наклонение просто означает «произносится или пишется так, как будто дает команду или инструкцию». Несколько примеров:

  • Убери свою комнату
  • Закройте дверь
  • Вынести мусор

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

Например, сообщение по умолчанию, созданное при использовании git merge, гласит:

Merge branch 'myfeature'
----------------------
Revert "Add the thing with the stuff"
----------------------
Merge pull request #123 from someuser/somebranch

Это как бы отдача команды или приказа. Поэтому, когда вы пишете свои сообщения коммитов в императиве, вы следуете собственным встроенным соглашениям Git. Например:

  • Рефакторинг подсистемы X для удобочитаемости
  • Обновите документацию по началу работы
  • Удалить устаревшие методы
  • Выпуск версии 1.0.0

Поначалу писать таким образом может быть немного неудобно. Мы больше привыкли говорить в изъявительном наклонении, когда речь идет о сообщении фактов. Вот почему сообщения коммитов часто заканчиваются следующим образом:

  • Исправлена ​​ошибка с Y
  • Изменение поведения X

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

  • Если применить эту фиксацию, эта фиксация будет здесь будет ваша тема

Например:

  • В случае применения этот коммит произведет рефакторинг подсистемы X для удобочитаемости
  • В случае применения эта фиксация обновляет документацию по началу работы.
  • В случае применения эта фиксация удалит устаревшие методы
  • В случае применения этой фиксации будет выпущена версия 1.0.0.
  • Если применить, эта фиксация объединит запрос на включение #123 от пользователя/ветки

Обратите внимание, что это не работает для других неимперативных форм:

  • В случае применения этот коммит исправляет ошибку с Y
  • В случае применения эта фиксация изменит поведение X
  • Если применить эту фиксацию, будет больше исправлений для сломанных вещей
  • В случае применения этот коммит будет добавлять новые методы API.

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

6. Оберните тело на 72 символа

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

Рекомендуется делать это с размером 72 символа, чтобы у Git было достаточно места для отступа текста, при этом сохраняя в целом все, что меньше 80 символов.

Здесь может помочь хороший текстовый редактор. Например, Vim легко настроить так, чтобы текст переносился на 72 символа при написании коммита Git.

#while writing commit in vim
:set tw=72

7. Используйте тело, чтобы объяснить, что и почему, а не как

Этот коммит от Bitcoin Core — отличный пример объяснения того, что изменилось и почему.

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

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

Будущий сопровождающий, благодаря которому вы можете быть собой!

Используйте стандартное соглашение

Согласно официальному git Рекомендации по фиксации

….Наличие хорошего руководства по созданию коммитов и его соблюдение значительно упрощает работу с Git и совместную работу с другими. …….

Таким образом, выше 7 правил плюс одно дополнительное правило (если вы используете систему тикетов для отслеживания функций или историй пользователей).

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

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

[Ticket-123] Commit_Subject_Goes_Here

Ссылки и дополнительная литература: