Про многие моменты разработки есть очень много информации. Как писать комментарии, как именовать классы, методы, какие паттерны использовать и т.д. и т.п. Но есть одна область, в которой многие даже и не задумываются о том, что можно что-то улучшить — это написание коммитов.
Зачем это вообще нужно? Чтобы экономить время и нервы, не больше и не меньше. Это мы еще обсудим чуть позже, а пока рассмотрим как же вообще именуются коммиты.
Общий стиль
Если пройтись по тем же коммитам с 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 указан данный модуль. - Просто более насыщенная и понятная история развития проекта.
Заключение
Надеюсь, вы еще не заскучали. Пожалуйста, старайтесь использовать хороший стиль именования коммитов в своих проектах. Другие люди будут вам за это очень благодарны.
На этом всё. Если у вас есть интересные примеры именования из своих проектов, буду рад увидеть их в комментариях. Все ошибки в тексте можете присылать в личные сообщения.
Приятного кодинга!
Автор: olegafx
