[Перевод] Как оформять коммиты, чтобы потом не было больно

Несколько дней назад 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"
    
    

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

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

© Habrahabr.ru