Pull to refresh

Стиль именования коммитов

Reading time 4 min
Views 118K
the Octobi Wan Catnobi

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

Зачем это вообще нужно? Чтобы экономить время и нервы, не больше и не меньше. Это мы еще обсудим чуть позже, а пока рассмотрим как же вообще именуются коммиты.

Общий стиль


Если пройтись по тем же коммитам с GitHub, то можно увидеть довольно обширное количество вариантов написания коммитов. Основные рекомендации по написанию можно выделить такие:

Что сделать + для какой сущности + подробности (необязательно)

Старайтесь найти единый стиль для коммитов и придерживаться его. Для себя я нашел удобным такой стиль, когда я сначала указываю что я делаю. Например, add. После этого я указываю что-то, над чем я произвожу действие. Например, ui-bootstrap.js dependency. В большинстве случаев такой записи более чем достаточно. Если есть еще какая-то пояснительная надпись, то ее лучше вынести в отдельную большую запись, о чем мы еще поговорим. Если запись маленькая, но очень нужная, то можно дописать её прямо к коммиту. Но лучше еще раз задуматься, действительно ли нужна эта надпись, или она будет привлекать ненужное внимание.

Бывает так:
dependency for managing ui-bootstrap.js components was added here on 18.06.2013 by olegafx

Но лучше:
add ui-bootstrap.js dependency

Большие сообщения в коммите

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

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

replace twitter-bootstrap.css with pure.css

Made UI much cleaner.

BREAKING CHANGE. You need to use new class-names for grid-related elements.

Пишем сообщение с маленькой буквы

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

Бывает так:
Add ui-bootstrap.js dependency
ADD ui-bootstrap.js dependency

Но лучше:
add ui-bootstrap.js dependency

НЕ используем прошедшее время

Чем проще, тем лучше. Прошедшее время слишком усложняет чтение сообщений. Предстаьте, что вы обращаетесь к Git: «Git, добавь», «Git, удали» и т.д.

Бывает так:
added ui-bootstrap.js dependency

Но лучше:
add ui-bootstrap.js dependency

Убираем лишние знаки препинания

Например, зачем вам точка в конце сообщения? Итак понятно, что оно закончено. То же самое относится к точке с запятой.

Бывает так:
add ui-bootstrap.js dependency;

Но лучше:
add ui-bootstrap.js dependency

Русский язык


Нет ничего постыдного в том, чтобы использовать русский язык в коммитах. Но делать это нужно только в том случае, если вы на 1000% уверены, что данный код будет интересен только русскоязычным людям. Например, у вас есть скрипт для VK, который указывает на карте всех фанатов Стаса Михайлова. Очевидно, что это будет мало кому интересно среди зарубежных граждан. Да и для россиян тоже, если честно.

Причесываем коммиты перед отправкой


Все коммиты в локальном репозитории можно именовать как угодно. Если вам проще запомнить, что «temp commit 1» — это первая рабочая версия какой-то функциональности, а «temp commit 2» — это ее исправленная и отрефакторенная версия, то пожалуйста, никто особо вас ругать не будет. Но. Огроменное НО. Перед отправкой приведите, пожалуйста, свои коммиты в самый лучший вид. Для большинства случаев подойдет замечательная команда:

git rebase -i

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

Находим свой любимый стиль


Я нашел такой в проекте AngularJS. У них есть даже отдельный документ, посвященный оформлению коммитов. Все моменты, о которых я рассказал выше, есть в этом документе. И это прекрасно. Потому что мне приходилось искать эти моменты самому из разных источников, своего опыта, а здесь все лежит уже в одном месте и написано хорошим простым языком. Кратко рассмотрим основные моменты.

Указываем тип коммита

Есть несколько заранее определенных типов:
  • feature — используется при добавлении новой функциональности уровня приложения
  • fix — если исправили какую-то серьезную багу
  • docs — всё, что касается документации
  • style — исправляем опечатки, исправляем форматирование
  • refactor — рефакторинг кода приложения
  • test — всё, что связано с тестированием
  • chore — обычное обслуживание кода

Не всегда эти типы можно легко различить при написании приложения (например, refactor и chore), поэтому можно придумать свои.

Указываем область действия (scope)

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

Например, может быть область видимости модуля:
refactor(audio-controls) use common library for all controls

Или область видимости файла:
chore(Gruntfile.js) add watch task

Для чего всё это

Как я уже говорил в самом начале статьи, для сохранения времени и нервов! Путём упрощения следующих операций:
  • Автоматическая генерация списка изменений (CHANGELOG.md и подобные). Даже если он не сформируется полностью, то будет хотя бы какя-то отправная точка для внесения небольших поправок.
  • Игнорирование неподходящих коммитов при поиске места, где все сломалось (например, с помощью git bisect).Коммиты, улучшающие документацию, тесты, стиль кода и т.д. могут сразу быть пропущены. Если у вас сломался модуль audio-controls, то вы будете смотреть только те сообщения, где в scope указан данный модуль.
  • Просто более насыщенная и понятная история развития проекта.

Заключение


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

На этом всё. Если у вас есть интересные примеры именования из своих проектов, буду рад увидеть их в комментариях. Все ошибки в тексте можете присылать в личные сообщения.

Приятного кодинга!
Only registered users can participate in poll. Log in, please.
Как вы оформляете коммиты?
26.12% Произвольный порядок слов 384
40.07% С большой буквы 589
39.52% В прошедшем времени 581
34.69% По настроению 510
38.03% Качественно 559
1470 users voted. 351 users abstained.
Tags:
Hubs:
+27
Comments 51
Comments Comments 51

Articles