Перевод статьи «Writing Good Commit Messages: A Practical Guide».
Чтобы логи изменений в репозитории приносили пользу, члены команды должны условиться относительно того, как они будут писать сообщения коммитов и каких правил при этом будут придерживаться. То же касается и личных проектов.
Недавно я поднял эту тему в Twitter. Я просил, какими соглашениями по написанию сообщений коммитов пользуются мои читатели. Среди ответов были весьма интересные.
В этой статье я расскажу, почему вообще стоит беспокоиться о сообщениях коммитов и о том, как их писать.
Вступление: система контроля версий
Программное обеспечение для контроля версий это важная часть современной разработки программ.
На сегодняшний день самой широко используемой системой контроля версий является Git. Это проект с открытым кодом, изначально разработанный в 2005 году Линусом Торвальдсом — знаменитым создателем ядра ОС Linux. С тех пор проект активно поддерживается сообществом. Если вы не знаете, как работать с Git, вам поможет эта статья.
Что такое сообщение коммита?
Команда commit используется для сохранения изменений в локальном репозитории после того, как они были подготовлены (staged). Но прежде чем сохранить изменения, нужно сообщить Git, что именно вы сохраняете (поскольку изменений может вноситься очень много и в них можно легко запутаться). Хороший способ сделать это — добавить к коммиту комментарий, в котором будут описаны вносимые изменение. Этот комментарий и называется сообщением коммита.
Опции для работы с сообщениями
Вы можете создать сообщение коммита, добавив к команде git commit опцию -m и само сообщение в кавычках.
git add static/admin/config.yml git commit -m "Setup multiple roles for netlify-cms git gateway"
Добавив опцию -а, можно перезаписать последний коммит с любыми подготовленными изменениями или новым сообщением коммита. Делать это можно только с коммитами, которые еще не были отправлены в удаленный репозиторий.
git commit -a "Setup multiple roles for netlify-cms git gateway"
При помощи опции —amend можно перезаписать самый последний коммит с любыми подготовленными изменениями или с новым сообщением коммита. Применять эту опцию можно тоже для изменений в локальном репозитории.
git add . git commit --amend -m "Update roles for netlify-cms git gateway"
Почему сообщения коммитов должны быть непременно «хорошими»?
Возможно, вы работаете над личным проектом и думаете, что он вообще не нуждается ни в каких особых сообщениях коммитов: вы-то всегда знаете, что и почему вы меняли. Но это сейчас вы работаете в одиночку. А что, если придется работать в команде, например, над проектом с открытым кодом?
Хорошо продуманные сообщения коммитов это лучший способ сообщить контекст вносимых изменений другим разработчикам, работающим над этим проектом, а также напомнить этот контекст себе самому в будущем. Вам случалось запустить git log в каком-нибудь своем старом проекте и поразиться, какие странные сообщения коммитов вы оставляли там? Со временем становится сложно объяснить, почему были внесены те или иные изменения в коде, и вы начинаете жалеть, что не прочитали статью, подобную этой, раньше, и не начали писать хорошие комментарии.
Сообщения коммитов могут рассказать вам, почему было сделано изменение, а когда вы понимаете все «почему», разработка и совместная работа над проектами становятся куда более эффективными.
Как писать сообщения коммитов в Git
До сих пор в своих личных проектах я
пользовался только git commit -m "Fix X to
allow to use Z" («Исправь Х, чтобы позволить
Y использовать Z»), то есть, добавлял
только заголовок коммита, без дополнительных
описаний. Это отлично подходит для
небольших и понятных изменений вроде
git commit -m "Fix typo in README.md" («Исправь
опечатку в README.md»), но когда изменения
более значительны, могут понадобиться
дополнительные подробности.
Использование редактора
Запустите git commit без сообщения и всяких опций. В результате откроется назначенный по умолчанию текстовый редактор, чтобы вы могли написать свое сообщение коммита.
Назначить редактор можно следующим образом:
git config --global core.editor nano
При помощи этой команды мы назначили nano дефолтным редактором в настройках git. Вы можете заменить «nano» на «emacs», «vim» или какой-то другой редактор.
В открытом окне редактора первая строка текста это заголовок коммита (короткое описание изменений), после нее идет отступ, а затем более подробное описание изменений — тело сообщения коммита.
<Summarize change(s) in around 50 characters or less> <More detailed explanatory description of the change wrapped into about 72 characters>
Использование командной строки
После первой опции -m идет заголовок коммита (короткое описание), а после второй — расширенное описание (тело сообщения).
git commit -m "Subject" -m "Description…"
Как писать хорошие сообщения коммитов
Существуют разные соглашения о написании сообщений коммитов, которых придерживаются в командах. Я приведу только общие правила и советы по написанию хороших сообщений. Подходящий свод правил для личных проектов вы можете выбрать (составить) самостоятельно, а если работаете в какой-то компании или принимаете участие в проекте с открытым исходным кодом, все равно придется приспосабливаться под принятые там правила.
Можно даже использовать одно соглашение на работе, а для личных проектов пользоваться другим. Работу вы все равно когда-нибудь поменяете, а с ней, весьма вероятно, и соглашение по написанию сообщений коммитов.
Вот отличный шаблон хорошего сообщения коммита, написанный Tim pope.
Сообщение-заголовок. Краткое, до 50 символов. Начинать с заглавной буквы Более подробный поясняющий текст (если нужен). Должен вмещаться в 72 символа. В некоторых ситуациях первая строка сообщения коммита (заголовок) воспринимается как тема email-а, а остальной текст — как «тело». Пустая строка между темой и телом имеет большое значение (за исключением случаев, когда у вас вообще нет тела сообщения). Если заголовок и тело сообщения будут идти подряд, без разделения пустой строкой, это может сбить с толку такие инструменты как rebase. Глаголы в сообщении коммита следует писать в повелительном наклонении: "Fix bug" («Исправь баг»), а не "Fixed bug" («Исправлен баг») или "Fixes bug" («Исправляет баг»). Когда сообщения коммитов генерируются командами git merge и git revert, они пишутся именно в повелительном наклонении. Абзацы отделяются друг от друга пустыми строками. - Допускаются обозначения пунктов списка. - Обычно для пунктов списка используются знаки дефиса или звездочки с пробелом после них. Каждый пункт отделяется пустой строкой, но это вариативно. - Допускается обратный абзацный отступ. Если вы используете issue tracker, добавьте ссылку(и) внизу, вот так: Resolves: #123
Выглядит отлично, верно? Вот как вы можете улучшить и свои сообщения:
1. Указывайте тип коммита:
- feat: новая фича, добавляемая к приложению.
- fix: исправление бага.
- style: функции и обновления, имеющие отношение к стилизации.
- refactor: рефакторинг определенного участка кодовой базы.
- test: все, что касается тестирования.
- docs: все, что касается документации.
- chore: обычная поддержка кода, рутина.
Для обозначения типов коммитов можно также использовать эмодзи.
2. Отделяйте заголовок от тела сообщения пустой строкой.
3. Сообщение коммита не должно содержать никаких ошибок пробелов.
4. Убирайте знаки пунктуации, в которых нет необходимости.
5. Не ставьте точку в конце заголовка.
6. Заголовок и каждый отдельный абзац должны начинаться с заглавной буквы.
7. В заголовке сообщения используйте повелительное наклонение.
8. Используйте тело сообщения, чтобы описать вносимые изменения и причины этих изменений.
9. Не предполагайте, что ревьюер знает о проблеме, которую вы решаете: оговаривайте ее.
10. Придерживайтесь соглашения о сообщениях коммитов, принятого в вашей команде.
Заключение
Что касается сообщений коммитов, самое главное, чтобы они были понятными и осмысленными. В долгосрочной перспективе хорошие сообщения коммитов показывают, насколько вы хороши в роли командного игрока. Хорошие сообщения пригодятся не только вашим коллегам по команде. Но и вам самому в будущем, и контрибуторам проекта, которые придут вам на смену.
[customscript]techrocks_custom_after_post_html[/customscript]
[customscript]techrocks_custom_script[/customscript]