Comments 34
Уж сколько видел рекомендаций по составлению идеальных коммитов, но нелепое правило 72 символов так и кочует от статьи к статье. Авторы этих текстов хоть сами пробовали сжать консоль до 72 символов или просто копипастят рекомендации не глядя? Я ещё могу понять такую рекомендацию во времена SVGA мониторов с резрешением 800х600 пикселей или в мире, где фичу с переносом слов ещё не изобрели.
Посмотреть на консоль шириной 72
В этом коммит мессадже длина строки не ограничена, но в консоли шириной 72 символа всё выглядит вполне прилично и читабельно.
Для сравнения, комментарий ниже следует какому-то ограничению (но не 72) и выглядит это явно хуже:
Но с ограничением длины первой строки согласен. Первая строка должна максимально кратко и ёмко описывать суть изменений. Чтобы при просмотре списка коммитов можно было быстро сориентироваться, не тратя время на прочтение полного текста каждого коммита. Разве что 50 символов - это чересчур мало.
Ещё кратко коснулись стиля angular, но об отдельном стандарте, выросшим из данного стиля, совсем ни слова. Всем рекомендую ознакомиться - https://www.conventionalcommits.org/
ограничение 72 подразумевается все же для консоли шириной 80 (8 про запас, на отступы там или что, может стандартная табуляция в начале). впрочем это ничего не меняет, с вами я согласен.
Зависит от команды. Если команда согласна на 172 символа - вперед.
У нас в команде есть пользователи, любящие и умеющие эффективно работать на мелких ноутах. Для них ограничение в 72 символа - очень важно.
Для себя лично пришел к выводу: мне может и не важно ограничение в 72 символа, но придерживаться почти ничего не стоит. И кто и когда будет листать этот репозитарий, я не знаю, поэтому на всякий случай лучше придерживаться рекомендаций, в том числе и на длину строки, чтобы им было приятно.
Я бы добавил рекомендацию ссылаться на задачу в трекере. Очень помогает в археологических изысканиях
В случае российских программистов главное правило - грамотный английский с адекватной терминологией, чтобы читать без боли и смеха.
Пишите с заглавной буквы только первую букву темы
И какую проблему это решает?
По-моему, это снизит читаемость коммитов за счет того, что имена собственные и аббревиатуры потеряют привычный вид. Да и начала предложений в комментарии тоже должны выделяться.
Используйте повелительное наклонение
А вот это правило сильно раздражает. Коммит - это решение задачи, а не ее постановка.
В английском использование повелительного наклонения может быть разумным (но тогда не надо было переводить текст сообщений коммитов). Если сообщения коммитов на русском, то это вредная рекомендация, и причастие в прошедшем времени более удачно смотрится.
Используйте повелительное наклонение
В английском повелительное наклонение имеет начальную форму (без суффиков), и это соответствует общей тенденции упрощать технические надписи — убирать артикли, местоимения и т. д. (типа “no step”). В русском прошедшее время всё же выглядит более уместным.
Я не понимаю, почему коммит мне приказывает вместо того чтобы рассказать что и почему в нём было выполнено)
Conventional Commits (автор, видимо, не в курсе как это называется, приводя в пример Angular) тоже выглядят иногда не очень удобно, особенно если коммитать из какой-нибудь IDE где работа с коммитами делается из-за угла в маленькой панельке и становится без дополнительных действий вообще непонятно, а что же там вообще происходит, потому что места там на 4-5 слов. Да и не вижу я смысла 100500 раз писать feat: если и так очевидно, что это по дефолту для большинства задач, а фиксы всё равно будуть содержать слово fix в контексте. То же самое если смотришь изменения через какой-нибудь Tig. По этой же причине, если нет каких-то требований на конкретном проекте, номер задачи я стараюсь добавлять в конце заголовка коммита и тогда он читается как "Что сделали, почему (какую задачу решали)"
Ну, шестое правило вообще переведено некорректно. Подстрочно может быть и точно, но некорректно. Если "… чтобы логически завершал предложение «Применение коммита позволит...» ", то повелительное наклонение там вообще никаким боком: "позволит исправьте ошибку". И в примере используется именно инфинитив.
Не надо чисто языковые правила цельнотянуто тащить из языка в язык. Ни человеческий, ни ЯП. Лично я комментарии на английском начинаю с инфинитива ("replace foos with bars"), а если на русском, то объясняю, что сделано ("Перекрашена кнопка", "Исправлен квиксорт на пузырек")
Не увидел рекомендаций писать коммиты на английском языке.
Я думаю, что в отдаленном будущем мы увидим как какой-нибудь IntelliJ IDEA переводит сопроводительный комментарий комита на лету и дает рекомендации если они пустые. Во всяком случае в тех репах по которым я шарюсь очень много комментов и описания коммитов на упрощенном китайском. Вполне логично, что однажды их переведут чтобы разработчики сосредотачивались на коде, а не на тексте коммитов.
Если лучший код - тот который не написан, то лучший коммит это тот который не отправлен ?
первая рекомендация: понять на каком этапе ваш проект
если проект на начальной стадии - например, вы работаете один, вы тестируете гипотезы, что-то тестируете, и при этом результаты фиксируете в репозиторий - то никто не будет читать ваши коммиты - забейте и пишите что хотите
если проект растет и вас два-три человека - но вы общаетесь, обсуждаете, все в курсе всего - никто не читает коммиты - забейте и пишите что хотите
если ваш проект подрос, начал использоваться вами в рабочей среде, вы стали реже в него писать - о, да, пора писать суть в коммитах, но если там пару опечаток поправили - забейте и напишите fix
если уже проект подзаматерел, работает, вы начали версионировать, да и команда побольше и проект стал частью чего-то большего - пора применять правила написания коммитов )))
вы работаете один, вы тестируете гипотезы, что-то тестируете, и при этом результаты фиксируете в репозиторий - то никто не будет читать ваши коммиты
Изучая новый для себя проект, я одним из первых шагов пытаюсь выяснить логику тех или иных архитектурных решений. Для этого обычно приходится читать первые коммиты.
А зачем тогда вообще репозиторий? Ну накалякали на локалхосте, сделали "Папка 1", "Ещё один папка", "Папка в папке", как диды в школе завещали - и хватит. Нафиг эту культуру разработки, привыкать к нормальному как к чему-то подразумевающемуся по умолчанию...
Правило номер 0.
Если в проекте уже приняты какие-либо правила оформления коммитов, используйте их, даже если это полностью противоречит вашему любимому своду правил. Безобразно, зато единообразно.
git commit -m "Улучшить UI: обновить header.js и footer.js"
Мне кажется, комментарии, где главное смысловое слово - "улучшить" и/или "обновить", совсем не информативны. Что, разве кто-то сознательно ухудшает код или дизайн? Все делается для улучшения, иначе это саботаж)
Постройте комментарий таким образом, чтобы он логически завершал предложение «Применение коммита позволит...»
Правило 6 про использование повелительного наклонения, на мой вкус, выглядит странно. Это, скорее, относится к постановке задачи - сделать что-то. На практике с такой логикой про "применение коммита позволит" не приходилось сталкиваться.
Распространенная в среде разработчиков ошибка – отношение к Git-репозиторию как к обычному хранилищу резервных копий.
Интересно почему же она распространённая?)
только засоряют ваш Git-лог
почему бы не чистить это лог периодически, освободив ггигабайты места и уменьшив углеродный\информационный след?
Хорошо составленные commit messages очень важны, они помогают нам самим в будущем извлечь максимальную пользу из своих стараний и продуманности.
Как именно? Открываю я трёхлетний красивый коммит и что? Как он поможет решить задачу?
Некоторые мысли:
Если нужна история проекта - читайте релиз-ноутсы написанные по-человечески для людей от тех-райтеров, вместо чтения истории срезов состояний кодовой базы от уходящих-приходящих но-нейм разработчиков.
Новый разработчик в команде может глянуть на историю чисто ради оценки интенсивности разработки, ну и принципов именования коммитов в комманде. А так, вникай в предметную область, изучай кодовую базу, общайся(!) с коммандой, проходи онбординг, делай таски, оставляй после себя код лучше чем был.
Гит и коммиты - это как источник истины\база\хранилище\блокчейн если угодно, а коммиты - типа миграций что-ли. Но точно уж не для чтения глазами истории проекта или "коммуникаций"
Ах, удобно вырезать\вставить\черри-пикнуть какой-то красивый понятный атомарный коммит. Обычно это делается в рамках одного разработчика, в рамках одной фичи, в рамках небольшого промежутка времени, в общем в рамках одного понятного контекста. Никто не будет перемещать коммиты годичной давности.
Ещё миф - понятные атомарные коммиты годичной давности помогут что-то там разобраться в каком-то забагованном бизнес-процессе.. ага. Иди, и общайся (лучше ртом вживую), распутывай код, двигай проект вперёд. Есть шанс сделать лучше. В этом твоя ценность как прикладного разработчика. История коммитов - это то что уже было, прошло, надо забыть, оно никому не надо (можно даже подчистить их чтоб места освободить).
О, гит-коммиты можно привязывать к таск-треккеру. Типа удобно посмотреть начальную таску в одну строчку, которая три раза успела эволюционировать в процессе разработки. А если этот трекер поменяется? High cohesion на лицо.
История коммитов - это то что уже было, прошло, надо забыть, оно никому
не надо (можно даже подчистить их чтоб места освободить).
История коммитов может как минимум помочь понять причину возникновения бага (иногда возникновение могло случиться достаточно давно) только за счет понимания, что именно изменилось. Так что совсем уж бесполезным и ненужным это дело никак не назовешь. А хорошо составленные тексты коммитов как минимум облегчают поиск нужного, с тем самым изменением.
Вместо первой половины статьи можно просто научить людей пользоваться amend и squash.
«Хороший коммит» и «ваш коммит»: как написать идеальный комментарий в Git