[Перевод] Как оформять коммиты, чтобы потом не было больно
Несколько дней назад David Demaree, главный по Typekit в Adobe, издал крутую книжку «git для людей». Чтобы привлечь к ней внимание, он опубликовал выжимку самой, на мой взгляд, интересной главы — как оформлять коммиты чтобы и волки были целы, и овцы сыты, и писец не пришел. А я за эти выходные подготовил выжимку из выжимки — сокращенный и адаптированный перевод, чтобы можно было быстро прочитать и добавить в копилку своего опыта самое ценное.
Искусство Коммитов
Комментарий к коммиту, возможно, является самой важной его частью, так как это единственное место, где написано не только что изменилось, но и зачем.
— из комментов
Хороший комментарий к коммиту — короткий. И не только потому что краткость — сестра. Сообщения к коммитам чаще всего читают в логе изменений, где их будет много. Рассматривайте каждое сообщение как заголовок новости в интернете: оно должно быть достаточно коротким чтобы вы могли быстро пролистывать новости и содержать ровно столько информации чтобы вы могли найти важное лично для вас. Если у вас в команде больше пары программистов, то лог коммитов позволяет быть в курсе того, что происходит в проекте. Git не накладывает ограничений на длину сообщения, после краткого анонса вы можете добавить несколько параграфов текста:
Updated Ruby on Rails version because security
Bumped Rails version to 3.2.11 to fix JSON security bug.
See also http://weblog.rubyonrails.org/2013/1/8/Rails-3-2-11-3-1-10-3-0-19-and-2-3-15-have-been-released/
Обратите внимание, что сообщение целиком содержит довольно много информации, а первая строка — краткую выжимку. Потому что в логе вы увидите только первую строку:
commit f0c8f185e677026f0832a9c13ab72322773ad9cf
Author: David Demaree
Date: Sat Jan 3 15:49:03 2013 -0500
Updated Ruby on Rails version because security
Ваш любимый текстовый редактор
git интегрируется как с консольными редакторами (vim, emacs), так и с графическими (Atom, Sublime, TextMate). Вызванный без --message git передаст заготовку текста настроенному редактору. После редактирования сообщения достаточно сохранить открытый файл и закрыть редактор, git определит что сообщение было измененино и использует его. Пример интеграции git с Atom:
$: git config --global core.editor "atom --wait"
Для каждого редактора нужны свои ключи командной строки, и в справке GitHub вы можете найти хороший обзор как настраивать популярные текстовые редакторы.
Комментарий к коммиту
Кода вы пишите комментирй к коммиту, я рекомендую придерживаться следущих правил:
- Несите пользу
Помните, что назнаечение комментария — дать вашим коллегам понять, что происходит в проекте. Поставьте себя на место читателя и подумайте, как лучше охарактеризовать зачем был сделан этот коммит.
- Остерегайтесь графоманства
Часто нам хочится написать «дурацкие баги» или «исправил проблему». Не поддавайтесь этой слабости, старйтесь максимально четко и ясно напсать что и зачем было сделано.
- Линкуйте информацию
Если коммит связан с какой-то внешней информацией — багрепортом, статьей в вики или чем-нибудь еще, то очень хорошей идеей будет явно указать это в комментарии к коммиту,
напирмер такМногие багтрекеры (включая встроенный в github) интегрируются с git и автоматически помечают баги как исправленные, если встречают в комментарии к коммиту номер этого бага вместе с зарезервированным словом, таким как fixes в этом примере.Replace jQuery onReady listener with plain JS; fixes #1357 - Будьте (достаточно) подробны
Не пишите что поменялось — это всегда видно по диффам. Пишите зачем были внесены изменения. Это как раз то, что по диффам не видно. Старайтесь уместить первую строку в 70 символов — дополнительную информацию всегда можно написать отдельным параграфом после пустой строки.
- Будьте последовательны
Чтобы ваш лог изменений читался как единая новостная лента — уделите немного времени, чтобы объяснить команде как лучше писать комментарии для коммитов. Хорошей идеей будет создать страницу в вашей вики (у вас ведь есть внутренняя вики?) с примерами хороших и плохих комментариев.
- Используйте глаголы
Часто возникает соблазн написать комментарий к коммиту вида «исправления». Но помните, что лог изменений — это история ваших действий над проектом, а действия лучше всего описывать глаголами. Если этого не делать, то очень легко деградировать до таких вот
комментариевКроме того, этого очень простое правило, которому легко следовать: «я только что поменял код. Что и зачем я сделал?»,# Making the last homepage update before releasing the new site $: git commit -m "Version 1.0" # Ten minutes later, after discovering a typo in your CSS $: git commit -m "Version 1.0 (really)" # Forty minutes later, after discovering another typo $: git commit -m "Version 1.0 (oh FFS)"например$: git commit -m "Update homepage for launch" $: git commit -m "Fix typo in screen.scss" $: git commit -m "Fix misspelled name on about page"
Ваши комментарии?
Надеюсь, этот перевод будет полезен многим хабрачитателям. Я, как разработчик, разделяю мнение автора и с удовольствием обсужу в комментах непростой вопрос создания читаемого лога коммитов.
