Как оформлять коммиты, чтобы потом не было больно

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

Комментарий к коммиту

Кода вы пишите комментарий к коммиту, я рекомендую придерживаться следущих правил:

• Несите пользу

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

• Остерегайтесь графоманства

  Часто нам хочится написать «дурацкие баги» или «исправил проблему». Не поддавайтесь этой слабости, старайтесь максимально четко и ясно напсать что и зачем было сделано.

• Линкуйте информацию

  Если коммит связан с какой-то внешней информацией — багрепортом, статьей в вики или чем-нибудь еще, то очень хорошей идеей будет явно указать это в комментарии к коммиту,

  например так

  Replace jQuery onReady listener with plain JS; fixes #1357
  

  Многие багтрекеры (включая встроенный в github) интегрируются с git и автоматически помечают баги как исправленные, если встречают в комментарии к коммиту номер этого бага вместе с зарезервированным словом, таким как fixes в этом примере.

• Будьте (достаточно) подробны

  Не пишите что поменялось — это всегда видно по диффам. Пишите зачем были внесены изменения. Это как раз то, что по диффам не видно. Старайтесь уместить первую строку в 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"
  

Ваши комментарии?

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

Автор: Voximplant

Источник