Комментарии 51
> старайтесь использовать хороший стиль именования коммитов в своих проектах
В командных проектах есть договорённость (номер тикета, описание, зависимости)
А в личных точно по настроению… бывают и не приличные :))
В командных проектах есть договорённость (номер тикета, описание, зависимости)
А в личных точно по настроению… бывают и не приличные :))
У меня на этот случай есть небольшой хук, который добавляет название ветки к сообщению коммита.
Спасибо. Очень вовремя. Раньше слабо задумывался о том, как оформлять сообщения к комитам.
А сейчас кодовая база разрослась, надо наводить порядок. А тут как раз ваша статья.
А сейчас кодовая база разрослась, надо наводить порядок. А тут как раз ваша статья.
Не согласен с пунктами про большие буквы, знаки препинания и прошедшее время.
При всей лаконичности, сообщения должны быть написаны на нормальном языке — например вот тут у вас времена намешаны, в результате если просто прочитать это сообщение, то может показаться, что вы улучшили UI, а теперь просите кого-то заменить twitter-bootstrap.css на pure.css:
При всей лаконичности, сообщения должны быть написаны на нормальном языке — например вот тут у вас времена намешаны, в результате если просто прочитать это сообщение, то может показаться, что вы улучшили UI, а теперь просите кого-то заменить twitter-bootstrap.css на pure.css:
replace twitter-bootstrap.css with pure.css
Made UI much cleaner.
В статье по этому поводу всё написано:
В основном сообщении не используется прошедшее время. В пояснительной записке можно писать всё, что угодно, как угодно.
Предстаьте, что вы обращаетесь к Git: «Git, добавь», «Git, удали» и т.д.
В основном сообщении не используется прошедшее время. В пояснительной записке можно писать всё, что угодно, как угодно.
Это бред. Мы не обращаемся к гиту, мы пишем commit message для log'а. Git не Siri.
Никому ничего не навязываю. Мне удобнее писать так. От «Added» коммит понятнее не станет, потому что итак понятно, что он был в прошлом.
Зачем же вы в статье прошедшее время использовали, и так же понятно, что она в прошлом написана. :)
То есть соблюдать банальные правила английского языка — необязательно? Более того, прошу вас привести вывод
git log --oneline -20
Что именно вы не сможете прочитать в такой истории?
Либо Fix for a few issues, либо Fixed a few issues. Тут надо определиться что в commit message пихать: описание коммита, или описание выполненных действий в рамках коммита.
В данном случае — ни то, ни то.
Ну так и напишите тому человеку. Мне-то вы зачем это пишете? :)
Вы привели мне пример, я на него ответил. Вы придерживаетесь того же стиля что и автор данного коммита?
Я придерживаюсь стиля, описанного в статье. Во-первых, я бы указывал конкретные «issues». А во-вторых, «fix issues» — вполне нормальная конструкция.
Fix security issues
В статье по этому поводу всё написано:Я не говорю, что не заметил вашего обоснования этих советов в статье. Я говорю, что я лично с ними не согласен, и привожу свое мнение. Я не хочу представлять, что я обращаюсь к Git. Git Не будет читать эти сообщения, их будут читать другие разработчики. Соответственно, я считаю, что человеку удобнее будет и понятнее читать
Fixed a critical issue in module.cpp; please refer to readme.txt for more information.а не
fix(module.cpp) critucal issueЗаметьте, я не призываю писать в commit message эссе на 10 листов. Но можно одновременно писать и кратко, и грамотно — с нормальными временами и знаками препинания.
Additional info in readme.txt.
Полностью согласен с Вами по обоим пунктам. Начинаю с прописной буквы и всегда пишу в прошедшем времени.
Я просто оставлю это здесь
tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
Думаю, Вы путаете прошедшее время и третье лицо.
А что делать, если надо коммитнуть кучу файлов?
Например, я добавил или изменил функциональность в некоторых базовых классах — хорошо бы для каждого класса описать в комментарии к коммиту, что изменилось, чтобы когда-нибудь потом глядя историю одного файла видеть, что в нём менялось с каждым коммитом, и какую ревизию открывать, если вдруг надо вернуть старую функциональность. Но одновременно весь коммит добавляет или изменяет функциональность всего приложения — это тоже неплохо бы описать.
Писать длинный-длинный комментарий ко всему коммиту? Или коммитить сперва базовые классы отдельно, с комментированием изменений?
Например, я добавил или изменил функциональность в некоторых базовых классах — хорошо бы для каждого класса описать в комментарии к коммиту, что изменилось, чтобы когда-нибудь потом глядя историю одного файла видеть, что в нём менялось с каждым коммитом, и какую ревизию открывать, если вдруг надо вернуть старую функциональность. Но одновременно весь коммит добавляет или изменяет функциональность всего приложения — это тоже неплохо бы описать.
Писать длинный-длинный комментарий ко всему коммиту? Или коммитить сперва базовые классы отдельно, с комментированием изменений?
Не знаю, как другие делают, но у меня комментарий к коммиту отвечает на вопрос: что я сделал в данном коммите. Поэтому я все пишу в прошедшем времени. И использование/неиспользование заглавных букв — дело привычки. Тут уже все от принятых стандартов зависит.
Что вы сделали я могу в самом коммите посмотреть, комментарий должен объяснять ЗАЧЕМ вы это сделали. Очень сильно это помогает в командах, где работают в разных часовых поясах.
Ну можно посмотреть на это не со стороны разработчика, а со стороны мэйнтейнера.
Для него коммит отвечает на вопрос: «Что произойдет, если я пульну или смержусь с ним?»
Хотя лично я пишу в прошедшем времени.
Для него коммит отвечает на вопрос: «Что произойдет, если я пульну или смержусь с ним?»
Хотя лично я пишу в прошедшем времени.
Самое главное — это указывать issue (через #ISSUE_ID) к которому относится коммит. Очень полезно при серьезной работе на github.
Остальное — мелочи.
Остальное — мелочи.
Не согласен про мелочи. Так и представляю:
А так да, многие системы управления проектами подхватывают ссылки на коммиты, если указывать номер тикета.
$> git log --pretty=oneline
fd6ab367a690e2dd438e3282ea9d2c8415f2296a #54!!!
afd843c40a9e5df6663dbf122f673d1c2eea77bf #42, #43 and #35
7ad7a34bef74124100465eac02241a0484b2f4db #31, #32
А так да, многие системы управления проектами подхватывают ссылки на коммиты, если указывать номер тикета.
Гит прекрасен тем, что позволяет полноценно работать и без интернета. Не спорю, указывать номер полезно, но чем вам поможет номер бага/тикета, когда вы не можете его прочитать? Более того, номер тикета — это несколько дополнительных кликов в браузере. Комментарий, который объясняет, для чего сделаны изменения, сохранит вам время и нервы.
Комментарии в настоящем времени читаются довольно странно. Коммит — это фиксация того, что мы сделали.
А ещё можно не мудрствовать, а просто вписывать номер задачи.
Я бы к этому добавил краткое описание. Полезно, чтобы другие члены команды в общих чертах представляли что произошло без необходимости обращатсься к трекеру. Например:
Теперь окинув взглядом историю можно быстро оценить что произошло за последнее время.
[SDK-513] Added compile-time check that ... supports ...
[ABC-1231] Enabled progress indication
[ABC-1311] Deleted unused code
Теперь окинув взглядом историю можно быстро оценить что произошло за последнее время.
Пишу имя тикета в JIRA, затем текст коммита в прошедшем времени. Мне кажется, так удобнее читать :)
Совсем недавно GitHub обновил дизайн, сосредоточившись, как это сейчас принято, на контенте. В контексте гихаба (а им, я уверен, пользуются многие хабровчане), именование коммитов в прошедшем времени выглядит гораздо логичнее, чем в настоящем:
Я стараюсь придерживаться следующего стиля: «Номер задания в багтрекере или затронутая область подсистемы (пространство имён): описание изменений». Пространство имён указываю либо общее для группы изменений либо пишу несколько подобных записей в одном коммите (если так вышло, что в одном коммите приходится фиксировать, например, несколько изолированных друг от друга изменений и изменение, затрагивающее файлы всех этих изолированных изменений). В целом, стараюсь фиксировать изолированные изменения по отдельности (если речь не идёт о черновой стадии работы над индивидуальным проектом). Описания стараюсь писать безотносительно времени (описывая изменение как факт).
Примеры нескольких коммитов:
Примеры нескольких коммитов:
- ESH-419: тут либо дублирую заголовок из багтрекера либо перефразирую его в более подходящий вид (если заголовок, заданный автором задания в багтрекере не совсем точно соответствует вносимым изменениям)
- components.shop.basket: добавление поддержки товара типа «ноутбук» в корзине покупок
- components.shop: исправление ошибки взаимодействия корзины покупок и списка товаров
В паре личных проектов использовал следующую нотацию:
В начале в квадратных скобках ставится модификатор действия:
+: added
— : deleted
*: modified (любая модификация, кроме фикса, которая хорошо описывается как «изменение»)
f: fixed
Далее идёт объект, над которым совершалось изменение (без глагола).
Многострочные комментарии не использовались, так как любое слишком крупное изменение разбивалось на два коммита.
После объекта идёт опциональный параметр, который записывается как
В конце обязательно ставится точка.
Мерж-коммиты, как правило, содержали описание основных фич, которые были смержены.
В целом, концепция была неплохая, но и без неё тоже неплохо работается. Тем более, если работаешь над проектом один. Описание коммита важно, но содержание важнее.
Сейчас в личных проектах пользуюсь нотацией «по настроению».
В начале в квадратных скобках ставится модификатор действия:
+: added
— : deleted
*: modified (любая модификация, кроме фикса, которая хорошо описывается как «изменение»)
f: fixed
Далее идёт объект, над которым совершалось изменение (без глагола).
[+] Tests for component X.Многострочные комментарии не использовались, так как любое слишком крупное изменение разбивалось на два коммита.
После объекта идёт опциональный параметр, который записывается как
[/]. Это индикатор т.н. partial-коммита, который не переводит проект в целостное состояние. Обычно, такие коммиты создаются в пылу кодинга, а потом подчищаются с помощью amend / rebase на свежую голову.В конце обязательно ставится точка.
Мерж-коммиты, как правило, содержали описание основных фич, которые были смержены.
В целом, концепция была неплохая, но и без неё тоже неплохо работается. Тем более, если работаешь над проектом один. Описание коммита важно, но содержание важнее.
Сейчас в личных проектах пользуюсь нотацией «по настроению».
Action. short desc. issue#
Fix. internal error during on-boarding. #1192
Feature. add pckry everywhere. #1193 #1194
Fix. too many requests to facebook during usual tasks. #1201 [WIP]
Fix. internal error during on-boarding. #1192
Feature. add pckry everywhere. #1193 #1194
Fix. too many requests to facebook during usual tasks. #1201 [WIP]
Я предпочитаю писать комментарии к коммитам в прошлом времени, но качественно.
action<. short desc>
<[fix/ref] issue id1: what was made for issue1>
<[fix/ref] issue idN: what was made for issueN>
short desc — до 60 символов
action — только в прошедшем времени:
В теории может быть ещё длинное описалово посередине с несколькими абзацами, но подобные вещи стараюсь избегать.
Я не пишу это в гите. И не работаю в гите. Но мои проекты на гитхабе)
система контроля версий может поменятся — история должна быть читабельной.
багтрекер может поменятся — хорошо если с сохранением тасков.
интернета может не быть — никаких ссылок
<[fix/ref] issue id1: what was made for issue1>
<[fix/ref] issue idN: what was made for issueN>
short desc — до 60 символов
action — только в прошедшем времени:
В теории может быть ещё длинное описалово посередине с несколькими абзацами, но подобные вещи стараюсь избегать.
Я не пишу это в гите. И не работаю в гите. Но мои проекты на гитхабе)
система контроля версий может поменятся — история должна быть читабельной.
багтрекер может поменятся — хорошо если с сохранением тасков.
интернета может не быть — никаких ссылок
Мой комментарий запоздал всего на пару лет, но всё же напишу. :) Тут много спорили о том, в прошедшем времени писать или в настоящем. Сами разработчики Git рекомендуют использовать императивный стиль:
Но каждый, конечно, решает сам. Хороший комментарий (пусть даже в будущем времени) будет лучше плохого, хоть и написанного по всем правилам.
Describe your changes in imperative mood, e.g. «make xyzzy do frotz» instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy to do frotz", as if you are giving orders to the codebase to change its behaviour.
Но каждый, конечно, решает сам. Хороший комментарий (пусть даже в будущем времени) будет лучше плохого, хоть и написанного по всем правилам.
Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.
Стиль именования коммитов