Время в комментах коммитов

Второй вариант грамотнее.

нет

Я пишу:

Adds feature XYZ

Или

Добавляет (реализует) возможность такую-то

В том смысле, что коммит добавляет фичу в проект. Не помню, где это подсмотрел, в какой-то грамотной статье.

Узбека ответ.

Feature is added

https://git.kernel.org/pub/scm/git/git.git/tree/Documentation/SubmittingPatches?h=v2.36.1#n181

Первый вариант правильный. Повелительное наклонение должно быть.

Форматированный HTML для зумеров: https://cbea.ms/git-commit/#imperative

Но если репа твоя собственная, то правила могут быть любыми, главное единообразие. Можно хоть по-русски писать.

New feature XYZ :3

Второй вариант. Первый звучит странно, хотя и встречал его (только это не настоящее время, а императив).

Сейчас в одном проекте, где в основном три человека коммитят (включая меня), и изредка другие: там разброд и шатание. Один использует первый вариант («Remove some old code»), другой (я) — второй («Removed duplicate […] menu entry»), третий — настоящее время («Moving images to correct dir.», да, ещё и всегда с точкой).

Просто пишите

+ feature XYZ

и не парьтесь.

А что если это фикс или изменение? Суть-то не в слове add, а в том, какую форму глагола используем.

Главная конвенция, которой всё же стоит придерживаться (даже если пишешь по-русски), это общая структура:

Заголовок в одну строчку (лучше до 50 символов)
<пустая строка>
Подробное описание

На неё рассчитано огромное количество софта, включая git log --oneline, UI гитхаба, подсветку в виме и т.д.

Соответствующее конвенции проекта. Если таковой нет, то императив, вроде все к нему сходится.

feat: add XYZ

https://www.conventionalcommits.org/en/v1.0.0/

Не помню откуда:

Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like git merge and git revert.

Когда на англицком пишу, то использую первый вариант. Читал какие-то рекомендации про это. Да и короче получается.

А когда по-русски - пишу «добавил фичу таку-то», «исправил ошибку такую-то».

Ладно, тогда gitmoji:

✨ feature XYZ
🚑️ feature XYZ
⚡ feature XYZ

и так далее.

Сказал казах…

Add feature XYZ

Использую первый вариант.

Как пещерные люди будем рисуночками общаться, ага. И эту срань ни погрепать нормально, ни разглядеть в git log при мелком шрифте, а без шрифта вообще одни квадратики.

Можно использовать язык без грамматического времени, например, 添加功能XYZ

Как пещерные люди будем рисуночками общаться

Предлагаете и дорожные знаки заменить на надписи словами?

ни погрепать нормально

Почему? Греп не умеет в эмодзи?

ни разглядеть в git log при мелком шрифте

Зачем пользоваться мелким шрифтом, зрение портить? Сейчас большие дисплеи вполне доступны по ценам.

а без шрифта вообще одни квадратики

Ну так поставьте шрифт!

Греп не умеет в эмодзи?

Даже если умеет, его ещё надо скопировать откуда-то сначала

Зачем пользоваться мелким шрифтом, зрение портить? Сейчас большие дисплеи вполне доступны по ценам.

При размере шрифта, комфортном для чтения букв, детали картинок трудноразличимы

Feature has been planted.

Решается автокомплитом по short name, типа начал писать ::ad и бац, предлагают эмодзи отвечающее за ::add::/::added:: вставить!

Это объективно подтверждено замерами времени на распознавание эмодзи по сравнению с буквой?

В зависимости от настроения.

Решается автокомплитом по short name, типа начал писать ::ad и бац, предлагают эмодзи отвечающее за ::add::/::added:: вставить!

Ок, что мне в bash_completion.d закидывать для этого?

Предлагаете и дорожные знаки заменить на надписи словами?

Аналогия некорректна. Дорожные знаки нужны, чтобы различать их издалека (разные цвета) и быстро, не тратить время на чтение, видеть их даже боковым зрением, а также они не должны занимать слишком много места. При этом, чтобы их понимать, требуется подготовка — их надо буквально заранее выучить в самом прямом смысле, чтобы сдать на права. Там это оправдано. Также стоит отметить, что они стандартизированы, и ничего другого, как и сопровождающего текста, там не нужно — лишь ограниченный набор.

Коммиты же — совершенно другое дело, там нет постоянного движения и не требуется быстрота реакции. Требуется точность и понимание, что за изменения были внесены. Происходит это в спокойной обстановке, где у человека есть время на чтение (по крайней мере отдельных предложений), читают их целенаправлено, а не так, что они могут «возникнуть» в неожиданном месте. При этом коммиты могут быть о чём угодно. Действительно многие из них могут начинаться с Add или Fix, но не так уж редко может быть что-то совсем другое, не входящее в любой, сколь угодно длинный список заранее заготовленных эмодзи (если, конечно, не доходить до абсудра с многими сотнями и тысячами эмодзи — на каждый третий глагол). Также к любому этому эмодзи всё равно потребуется текст о том, что именно было Added или Fixed. И текст этот, пожалуй, важнее этого одного глагола. А если мы всё равно читаем текст, то этот один «дорожный знак» своих задач не решает. Также эти эмодзи придётся заранее заучивать, если их больше двух-трёх. При том, что читать всё равно потом придётся, и даже после заучивания никакого мгновенного схватывания смысла через «знак» не получится — а лишнее время уже потрачего — не стоит овчинка выделки. Вот и выходит, что никакого смысла в этом нет, по крайней мере в аналогии с дорожными знаками.

Зато вот чему себя приучил, так это писать теги в commit message, примерно показывая к какой подсистеме относится этот коммит. Это помогает коммиты держать атомарными, сообщение держать короче, и меньше задумываться о том как его написать.

С другой стороны, задуматься о своем изменении – это хорошая практика, так как далеко не всегда сообщение коммита может совпадать с тем что этот коммит изменяет. Лишний раз обдумать свой патч возможно спасёт от часов отладки. :)

Как договорено. На одном проекте было можно писать коммит-месаджи по-русски и по-английски, даже так жилось нормально

Как договорено

Ну это понятно. А если договорённости нет, и сам решаешь, то как? Ну или для простоты, если это свой собственный проект.

P.S. Вообще надо было это в виде опроса делать. С бо́льшим количеством вариантов, естественно.

Тогда предлагаю вернуться к символам с клавиатуры, типа гит диффовских:

+++ feature XYZ

Осталось придумать трехзначные комбинации для распространненных причин типа fix, change, и вуаля, время ненужно!

Вообще учитывая последовательность процесса (сначала пишем код, потом текст коммита), писать коммит надо в прошедшем времени, описывая что было сделано.

Вообще учитывая последовательность процесса (сначала пишем код, потом текст коммита), писать коммит надо в прошедшем времени, описывая что было сделано.

При наличии живого code review коммиты часто редактируются уже после написания текста.

Feature has been planted.

One bug left.

А если для себя - то как хочешь, так и пиши, хоть через раз меняй. Вообще это всё не важно я лишь бы понятно было

Верно пишут выше. В английском повелительное наклонение.

https://www.freecodecamp.org/news/how-to-write-better-git-commit-messages/

В русском - немного сложнее с формулировками. Мы в команде решили описывать «что произошло» (т.е. добавлено то-то/реализовано/исправлено и т.д.). У нас, увы, требования по языку коммитов, да и английский далеко не у всех конёк 🤭

Add feature XYZ

Но вообще это мелочи.

Второе естественно. Первое выглядит как требование, а не отчет

Есть же рекомендации из официальной книги Pro Git.

https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project

Write your commit message in the imperative: «Fix bug» and not «Fixed bug» or «Fixes bug.» Here is a template you can follow, which we’ve lightly adapted from one originally written by Tim Pope:

Capitalized, short (50 chars or less) summary

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase will confuse you if you run the
two together.

Write your commit message in the imperative: "Fix bug" and not "Fixed bug"
or "Fixes bug."  This convention matches up with commit messages generated
by commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too

- Typically a hyphen or asterisk is used for the bullet, followed by a
 single space, with blank lines in between, but conventions vary here

- Use a hanging indent

Более того, сам Git использует императив для внутренних сообщений коммитов – Merge ... to ..., Revert ... и др. То есть правильный и самый распространённый вариант именно первый.

Get feature XYZ :)

Напомнило про https://whatthecommit.com/

В тикете должно быть побуждение (call to action) вместо фиксирования фактов. Т.е. «надо чтобы БД перестала стирать все файлы» вместо «БД стирает все файлы»

Соответственно в коммите результат этого побуждения, т.е. «added keeping some files out of deletion process»

Imperative mood, как деды завещали.

В JS мире сейчас еще принято начинать коммит с уебанских префиксов вроде fix:, feat: и что-то ещё. Во многих проектах и командах такое вижу. Я вообще не понимаю кто этим говноделам разрешил использовать что-то кроме shit:

Get feature XYZ :)

Получите, распишитесь! И поймите (в догонку) ;)

Мне кажется, я нашёл окончательное решение этого вопроса.

Стиль, который обычно рекомендуют использовать в заголовках коммитов, является ничем иным, как Headlinese. Это особый вид английской грамматики, использующийся в газетных заголовках и т.п. Именно отсюда идут настоящее время, отсутствие подлежащего, артиклей, точки в конце предложения, и прочие непотребства.

Если кому-то интересно, то есть ролик с подробностями на тытрубе: https://www.youtube.com/watch?v=d3hwrl0ACvU&t=169s

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