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

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

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

Общий стиль

Если пройтись по тем же коммитам с 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. У них есть даже отдельный документ ^[1], посвященный оформлению коммитов. Все моменты, о которых я рассказал выше, есть в этом документе. И это прекрасно. Потому что мне приходилось искать эти моменты самому из разных источников, своего опыта, а здесь все лежит уже в одном месте и написано хорошим простым языком. Кратко рассмотрим основные моменты.

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

Есть несколько заранее определенных типов:

• 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 указан данный модуль.
• Просто более насыщенная и понятная история развития проекта.

Заключение

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

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

Приятного кодинга!

Автор: olegafx

Источник ^[2]