Как правильно писать комментарии к коммитам?

Question

[knott]

Подскажите пожалуйста, как правильно писать комментарии к коммитам, что-бы не создавать себе грабли в истории и не получить подзатыльник от коллеги?

Есть ли какие-нибудь более-менее общепринятые гайдлайны по этому поводу?


Естественно приветствуются ответы основанные на собственном опыте.

Answer 1

[Владимир Чернышев]

В книге Pro Git рекомендуется писать название коммита (короткое описание) начиная с английского глагола в повелительном наклонении: «Fix», а не «Fixed» или «Fixing»

Answer 2

[wartur]

Нууу. Книжек я не читал, но если тут будут очень будет полезно.

> что-бы не создавать себе грабли в истории и не получить подзатыльник от коллеги?
Ну, надо договориться в начале со всеми, как вы будете это делать. А то странная вакханалия подзатыльников по всей команде начнется =)

Как у нас заведено:
У нас коммент разделяется на несколько частей.
1) условное слово, что сделано. fix (исправлено), unstanle (означает, что обновлять на рабочий сервер это версией нельзя)
2) на новой строке ссылка на багтрекер, в которой описана проблема ( http:// mantis/issue/id условно), и айди комментария(ев) в вопросе.
3) Возможные комментарии, через черточку на новой строке каждый
— коммент1
— коммент2

====== Пример 1

fix
http:// ....
- решено то
- решено сё

====== Пример 2

unstable
http//..... 1233, 1235
- не исправлена на чистовую версию синхронизация

====== Пример 3

fix
http//..... 1233, 1235</code>

Comments

[knott]

А были случаи когда коммиты делались не относительно трекера?

> unstanle
Вы, наверное, имели ввиду unstable?

[wartur]

Да, были.
В таком случае вторая строчка отсутствует, только перечисления исправлений

unstable — да, верно, очепятка

Answer 3

[Astashov_Anton]

tpope об этом писал: tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
Там про git, но это можно применять для любой VCS.

Answer 4

[madmaxcorp]

Ну у нас было: «Номер тикета в JIRA — сделано то-то»

Answer 5

[TheHorse]

Сейчас использую:
<Название название подсистемы>:<Что сделано.>
Example:
Gaia: Implemented type traits for memcpy relocation.

Критерии качества в этом контексте очевидны:
1. Комментарий должен быть таким, чтобы можно было понять где вносились изменения.
2. Комментарий должен быть таким, чтобы можно было понять что сделано.
3. Комментарий должен быть лаконичным.

Даты, ники и прочие вставлять не нужно потому, что эти сведения итак есть в СУВ.

Answer 6

[Vampiro]

Я себе представляю — что буду набивать в строке поиска, если придется искать именно этот коммит, и соответствующие слова вставляю. Мне кажется основной смысл комментария именно в отображении сути изменений и возможности потом найти кто это делал и когда, и откатить, если что. Даже когда в системе работаю я один помогает. Ну и приятно потом почитать как шел прогресс на прошлой неделе, например. :)

Answer 7

[Николай Турнавиотов]

О таких вещах обычно договаривается команда. у кого как. когда номер тикета, когда просто комментарий «фича такая-то»/«решение проблемы такой-то»

Answer 8

[easyman]

Если совсем ничего в голову не приходит — whatthecommit.com/

Answer 9

[Progrik]

У нас об этом статья есть: trilandev.com/2012/03/git-comments.html
Стараемся не отступать от её принципов

Comments

[knott]

Да, спасибо, уже прочитал её.

[Святослав Хусамов]

а где она теперь?