Comments 35
Используйте повелительное наклонение в заголовке
Для комментариев на русском языке (в приведенном примере комментарий именно на нем, родимом) смотрится крайне неестественно.
Повелительное наклонение все-таки предназначено для постановки задач, в то время как описание коммита про уже сделанное.
Логичнее бы смотрелось существительное, описывающее процесс, или прошедшее время.
Нашей конторе это не поможет… Тестировщики то и дело присылают задачи с заголовком "Ошибка программы". И когда таких задач несколько к ряду — утомительно заглядывать в каждую и определять, в какой области, хотя бы, проблема.
Повелительное наклонение все-таки предназначено для постановки задач, в то время как описание коммита про уже сделанное.Можно посмотреть на это с другой стороны. Описание коммита говорит от том что будет сделано если вы «чери-пикнете» его или сделаете слияние ветки с этим коммитом.
Обычно в каждой компании свой стиль коммитов. И это довольно неудобно...
Используйте повелительное наклонение в заголовке
Это применимо к английскому языку, в котором повелительное наклонение образуется как слово в инфинитиве без "to". В статье по ссылке примеры типа "if applied, this commit will fix bug #100500" В русском языке обычное повелительное наклонение будет звучать в заголовке очень странно ("исправь(те) баг №100500"), а форма повелительного наклонения, совпадающая с инфинитивом ("исправить баг №100500"), будет выглядеть чуть менее странно. Наверно, для русского языка нужно использовать инфинитив, а не "обычное" повелительное наклонение, если применять такую логику.
Интересная статья, спасибо. Переводить комментарии комитов не обязательно, ведь они и так всегда пишутся на английском.
Я так понимаю к категории "feat" относятся не только новые функции но и изменения в существующих? Куда в таком случае отнести оптимизацию?
Переводить комментарии комитов не обязательно, ведь они и так всегда пишутся на английском.
всегда пишутся на английском
Но почему? Не все работают на забугорье. Почему в чисто русскоязычной команде документация (коммиты) должна быть на английском? Некоторые изучали немецкий, и не владеют английским в достаточной мере. да и немецким тоже
Да никто никому ничего не должен, это лишь рекомендации, но ведь так проще: не надо переводить на русский термины из предметной области, имена классов и функций. Когда всё на одном языке, как-то проще работается, избегаются проблемы неточного перевода, да и потом, когда команда разрастется или изменится, поддержку продукта передадут в другую, не русскоязычную команду или даже компанию, будут проблемы. Но если с английским совсем уж туго, то пожалуйста. Процессы должны помогать, а не наоборот. Если это создаёт больше проблем, чем решает, то игнорируйте данный совет. Это лишь набор рекомендаций.
Add: Подсветка синтаксиса в редакторе (some_edit_form.php)
Del: Устаревший код и неактуальные комментарии в mycode.php
Fix: В форме «some_edit_form.php» поменял «Обновить» на «Сохранить»
Сразу видно, что сделано в данном коммите.
Подробное описание того, что сделано в коммите — часто бесполезная информация, это и так видно из самого коммита. Лучше писать почему это сделано именно так, а не иначе, какие были причины и мотивы, как принималось решение. Через год-два это будет намного интереснее.
Или просто, при просмотре истории сразу видно — кто когда и что делал. Не надо смотреть конкретные коммиты или историю конкретных файлов — всё уже на виду.
Ну а про «Историю принимаемых решений» — иногда ведут багтрекер (не на гите) и обсуждения ведутся там, а в историю гита помещается ссылка на соответствующее обсуждение. Или на запись в форуме/чате/вики…
Такой вариант тоже возможен, да. У меня просто, как правило, бывает цепочка такая: наткнулся в коде на странное место, запустил git blame, перешел на эту строчку, взял id коммита, а дальше git show . Оно сразу и коммент покажет, и автора, и время, и целиком то, что поменялось в этом коммите, всё на виду. Про багтрекеры и вики — полезно, да, и всё прекрасно, правда до тех пор пока они не грохнулись или не случится переезд с одной системы на другую, помню, долго мигрировали с ClearQuest в Jira, а перед этим в ещё из какой-то системы в ClearQuest… В идеале, конечно, происходит миграция старых тикетов в новую систему, но не всегда это проходит гладко, что-то теряется, ссылки и id становятся неактуальными, искать только полнотекстовым поиском по дескрипшену или комментам в тикету и надеяться что при миграции старый id корректно записался в комменты, и так далее..
Зачем далеко ходить, когда краткое саммари обсуждения, если такое было, можно прописать в коммит? Жалко одного-двух предложений?
Или даже так:
[+] Подсветка синтаксиса в редакторе (some_edit_form.php)
[-] Устаревший код и неактуальные комментарии в mycode.php
[*] В форме «some_edit_form.php» поменял «Обновить» на «Сохранить»и так далее
Если при этом принципиально именно сделать коммит и запушить его, то сделать отдельную ветку под эту задачу, закоммитить с комментарием "WIP", а потом, на другой машине, когда доведёте до логического конца, сделать commit --amend, написать новый комментарий, и запушить с --force обратно. Либо, что проще, не делать коммит вообще, а просто что-то вроде git diff > my_patch.diff && scp my_patch.diff remotehost:~/, а там уже git apply ~/my_patch.diff — продолжаете работать.
Если вы работаете с этим репозиторием один, то ничего плохого, дело ваше. Но надо уважать своих коллег, я считаю, иначе как потом анализировать историю изменений среди всего этого мусора? Коммит должен быть атомарным, то есть состояние системы должно быть законченное в какой-то степени. И не должен содержать побочных изменений, только что-то неразрывно связанное между собой. Это делается в том числе для того, чтобы можно было легко что-то откатить в случае необходимости, не затрагивая лишнее, и чтобы при этом система осталось рабочей.
Атомарность коммита это очень хорошо, но работает только когда программист сидит за рабочим местом круглые сутки и никогда не переключается от своей задачи к другой. А что делать, если при реализации какой-то фичи в коде тебе вдруг приходят и говорят срочно исправить баг в другой твоей фиче? Неужто клонировать проект в другое место? Если работник уезжает в отпуск, не доделав фичу? Если офис переезжает? Если проходит плановый апгрейд рабочего места?
Просто в применении dif'а вместо git'а я вижу первый шаг к тому, чтобы предложить создать zip-архив с git репозиторием и тащить его домой на флешке. И всё ради красоты в твоей личной ветке репозитория.
Это не так. Во-первых, не вместо git'а, а с его же помощью, это часть его функционала. Во-вторых, вариант с diff-ом я предложил как ещё один альтернативный вариант (не основной) применительно к одной конкретной ситуации — когда вам нужно быстро переключиться с одной машины на другую с минимумом телодвижений и без необходимости делать временные коммиты, добавлять файлы в них и придумывать для этих временных коммитов комментарии типа WIP. Такой ведь был изначально вопрос? Применять это для чего-то ещё я смыла не вижу. Каким боком это ведет к zip-архиву на флешке, я тоже не понимаю.
Атомарность коммита это очень хорошо, но работает только когда программист сидит за рабочим местом круглые сутки и никогда не переключается от своей задачи к другой. А что делать, если при реализации какой-то фичи в коде тебе вдруг приходят и говорят срочно исправить баг в другой твоей фиче? Неужто клонировать проект в другое место? Если работник уезжает в отпуск, не доделав фичу? Если офис переезжает? Если проходит плановый апгрейд рабочего места?
Не понимаю, в чем проблема-то? Значит делаете коммит в том состоянии, как есть сейчас, и переключаетесь на другую задачу. Если нужно ехать в отпуск или кто-то другой будет это допиливать — пушите этот коммит в отдельную ветку на сервере. Локально / на неофициальных ветках можно творить что угодно. Но перед мержем в мастер / релиз хорошим тоном считается всё причесать, хотя бы из чувства уважения перед коллегами, которым придётся через год в этом копаться.
А что делать, если при реализации какой-то фичи в коде тебе вдруг приходят и говорят срочно исправить баг в другой твоей фиче? Неужто клонировать проект в другое место?
Можно использовать git worktree.
Либо, что проще, не делать коммит вообще, а просто что-то вроде git diff > my_patch.diff && scp my_patch.diff remotehost:~/, а там уже git apply ~/my_patch.diff — продолжаете работать.
Имхо, это сомнительное "развлечение". Git как раз и предназначен для автоматического выполнения этих действий. С Git'ом это быстрее, надёжнее, удобнее. Я отношусь к системе Git как к инструменту, а не как к идеальной летописи, и поэтому допускаю в таких случаях неатомарные коммиты на неосновных ветках. При желании можно делать rebase --interactive и исправлять историю. Можно даже создавать отдельную ветвь на каждый неатомарный коммит, а потом объединять такие коммиты, как надо. Но, имхо, в этом немного смысла.
Так-то, я видел даже бэкапы git-репозиториев в zip архивах, и даже слышал про скрипты создания подобных архивов с возможностями оставить комментарий и применить патч. Но зачем это всё, когда информация в git автоматически реплицируется на несколько компьютеров, патчи применяются автоматически, комментарии и так предусмотрены, ещё и удобные gui инструменты для этого есть?
Да я просто накидываю разные варианты что делать, когда лень придумывать коммент для коммита :)
Я отношусь к системе Git как к инструменту, а не как к идеальной летописи, и поэтому допускаю в таких случаях неатомарные коммиты на неосновных ветках. При желании можно делать rebase --interactive и исправлять историю. Можно даже создавать отдельную ветвь на каждый неатомарный коммит, а потом объединять такие коммиты, как надо.
Так я то же самое и написал в первую очередь, как основной вариант.
Но, имхо, в этом немного смысла.
Смысл лишь в поддержании порядка и удобстве потом, когда надо change log собрать или что-то откатить. Откатывать атомарные коммиты куда проще.
Насчёт второго варианта, быстрее и удобнее — не всегда, бывает наоборот, сравните:
git status
git add file1 file2 file3 fileN
git commit
git pushи
git diff > patch
scp patch ...Использовать commit -a чтобы автоматически все файлы добавить не всегда прокатывает, потому что бывает что есть левые изменения, которые не нужны в коммите, и тогда либо добавлять все нужные файлы руками, либо commit -a и их потом придётся выковыривать с помощью всяких там ресетов и интерактивных ребейзов. Поэтому что "быстрее, надёжнее, удобнее" зависит от ситуации.
Применяйте то, что знаете, и то, что вам удобнее.
git diff > patch
scp patch ...
Если вместо "..." набирать реальные имя сервера, опции, логин, порт, пароль (опционально), имя каталога на сервере, то эти команды подлиннее будут. А значит, это сложнее (нужно всё данные вспоминать), есть возможность ошибиться и потерять данные.
Строка git add -A . && git commit -m "WIP" && git push менее подвержена ошибкам. В git уже есть конфигурация параметров ssh.
С копированием патча на флешку суть примерно такая же.
git status
git add file1 file2 file3 fileN
git commit
git push
В git extensions (правда, он под виндой) эти действия (в варианте -a) выполняются примерно в 4 нажатия кнопки мыши. Если нужно фиксировать не все файлы или не все изменения в файле, в gitextensions опять же есть такая возможность в GUI.
Да ради бога, как удобнее в вашей ситуации, так и делайте. Логин скорее всего не нужен так как совпадает с текущим обычно, порт как правило дефолтный, пароль либо запрашивается либо не нужен если по ключам авторизация идёт, каталог может быть ~/ или /tmp, имя сервера копируется из соседней вкладки консоли, ведь вам и так надо залогиниться туда чтобы продолжить работу и вы его так и так знаете… Так что в моём типичном случае всё ограничивается "scp patch server2:~/".
Если в вашем случае это получается сложнее, то спокойно не используйте, как будто вас кто-то заставляет делать именно так и никак иначе. Если в какой-то ситуации этот прием пригодится — хорошо. Не пригодится — тоже хорошо. Удобнее тыкать мышкой — да пожалуйста. Нужно пользоваться тем, что привычно и удобно.
Не знаю почему, но многие знакомые и я ставим три точки в таком случае
WIP (work in progress) ...
Учимся писать информативные комментарии к GIT-коммитам используя общепринятую семантику