Комментарии 42
Вопрос по коммитам. По каким правилам, коммит должен быть в повелительном наклонении? Разве это не краткое изложение проделанной работы?
Резюмируйте изменения в 50 символах или меньше Тут объясните их более детально, если необходимо. Выполняйте переносы строк примерно на 72 символах. В некоторых ситуациях первая строка комментания считается его заголовком, а все остальное - телом. Крайне важно отделять оделять одно от другого пустой строкой (если у сообщения вообще есть тело, конечно); различные инструменты типа `log`, `shortlog`и `rebase` не поймут вас, если заголовк и тело не будут отделены. Объясните здесь, какую проблему решает этот коммит. Уделите больше внимания тому, почему вы внесли эти изменения, а не тому, как именно вы это сделали (это объяснит за вас код). Есть ли сайд-эфффекты или другие неочевидные последствия у этих изменений? Если да, это нужно объяснить здесь. Параграфы разделяются пустыми строками. - Можно делать маркированные списки - Обычно в качестве маркера списка используется звездочка или тире с пробелом перед ними; но тут есть разные соглашения Если у вас есть баг-трекер [или система управления проектами], поместите ссылки на задачи в конце текста таким образом: Решено: #123 Смотрите также: #456, #789
А почему правила, сформулированные синьором разработчиком из RedHat (ну или там еще кем-то) должны быть применимы к другим проектам, другим компаниям, и другим людям?
Признаю, ваша правда. Каждый может как угодно делать, но есть определенные правила. Я сам то и не использую повелительное наклонение... Спасибо за ваше мнение!
Давайте называть вещи своими именами - это рекомендации, возможно от уважаемых и умных людей - но придерживаться их никто не обязан. Тем более если они не сформулировали ограничения на применимость своих рекомендаций (а я сколько видел таких советов - как правило ограничения никто не формулирует).
Ну т.е. к самим рекомендациям нет особых претензий - лучше коммиты оформленные по единому стандарту, чем какие попало. Вопрос скорее в соотношении трудозатрат на оформление, и профита, полученного в итоге. Я вот пришел к выводу, что кроме ссылки на jira, как правило больше ничего можно не писать - все равно через полгода эти тексты никому ничего не говорят, потому что они имеют смысл только в контексте, а в него еще надо попасть. Поэтому оставлять можно только то, что указывает на цель изменений - потому что сами изменения и так в коде и его истории остаются. А вот зачем сделали - это либо баг трекер, либо комментарии. И баг трекер лично мне удобнее.
сам то и не использую повелительное наклонение
Да скорее всего потому, что попробуйте сами себе объяснить, какую пользу вы получаете от его использования? А еще лучше - эту пользу измерить. И вряд ли у вас что-то путное намеряется (ну или как минимум - это сложно).
А потом ваша команда спешно переезжает на другой багтрекер и история превращается в тыкву) Поэтому недостаточно только номер таски писать. И вообще заставлять людей лишний раз ходить в тормозную жиру, потому что лень было нормально 4-5 слов написать по мотивам заголовка в той же жире - ну такое себе.
А потом ваша команда спешно переезжает на другой багтрекер
Ни разу в своей практике спешно не переезжал. И вообще переезжал один раз. С какой стати я должен о таком редком событии думать?
По очень разным причинам. То что это не случалось лично с вами - вообще ни о чём не говорит. Ну точнее это говорит о том, что у вас нет некоторого опыта. У других есть. И это всё ещё никак не характеризует за что вы так ненавидите людей из команды, что заставляете их каждый раз переть в жирную жиру, открывать в браузере таску (которая ещё не факт что правильно оформлена) и гадать, насколько то что вы сделали соответствует этой таске.
Да скорее всего потому, что попробуйте сами себе объяснить, какую пользу вы получаете от его использования? А еще лучше - эту пользу измерить. И вряд ли у вас что-то путное намеряется (ну или как минимум - это сложно).
На самом деле, конкретно для английского языка объяснение проще, чем кажется: глагол в повелительном наклонении короче всего, а на длину первой строки в коммите есть исторические ограничения. Я вот с точки зрения читаемости предпочитаю деепричастие ("adding"), на следующем месте - прошедшее время ("added"), но императив ("add") короче их обоих. Впрочем, я просто забиваю на обрезание первой строки.
Решено: #123 Смотрите также: #456, #789
#123 Смотрите так же - это задача или где хотя бы какие-то знаки препинания? Почему их нельзя разнести на отдельные строки? Писать номер основной задачи в title, а не в конце текста - это отличная практика, добавочный текст коммита зачастую никто не смотрит.
По ссылкам можно найти как чувачки из гитбука противоречат сами себе
Это правила из их команды, потому что разработка гита ведётся сильно иначе, чем ваши личные проекты и тем более проекты компаний. Сообщество разработчиков Git - это вообще отдельный мирок со своей атмосферой и правилами. Сегодня, чтобы сделать Merge Request в Git, нужно не слабо так постараться, потому что нельзя просто взять акк на gmail и написать в рассылку, они всё ещё требуют plain text с вот тем самым форматированием по 50 и 72 символа. И именно этим обусловлена данная рекомендация к оформлению коммитов - их текстовыми письмами. 99% других разработчиков эти ограничения слабо касаются.
По общепринятой конвенции коммиты на гите должны быть в повелительном наклонении. Нас сейчас учат не совсем так, как пишет автор, то есть указать первое основное слово и после него двоеточие - в первый раз вижу. Но за коммиты в неправильном оформлении (не в повелительном) существенно снимают баллы.
И этого также много значит
И этим всё сказано. Вчера увидел что github поддерживает markdown, но ещё не разобрался, поэтому каждый заголовок дублируется в ремарках. Заявки в повелительном наклонении репозиторию? - ну дичь же. Хватит это бездумно копировать, такая статья тут появляется каждый месяц и каждый раз в это тычут. Практического применения примерно ноль. Но если захочешь собрать, например, changelog через `git shortlog --no-merges master --not $(git describe --tags --abbrev=0)` выясняется, что его весь нужно переписывать.
| revert | Откат на предыдущие коммиты
revert не так работает, этот текст вводит в заблуждение
Вот эти огрызки feat, sec, refactor... что люди делают с сэкономленными буквами? Почему refactor можно написать, а feature - слишком длинно? Зачем вообще держать в тексте тысячи feature, если и так понятно что по умолчанию фичи пилишь?
Приветствую! Да, эта статья, моя вторая статья, вышла кривая, я уже это понял. Поддерживаю ваше мнение, но таких статей я еще мало видел, или я плохо искал. Спасибо за ваше мнение!
Их регулярно скрывают обратно в черновики, потому что ну... грабли одни и те же, людям поднадоело, реакция соответствующая.
Главное правило к коммитам - писать их. Так, чтобы людям в удобной форме доносилось, что сделано в этом коммите. Можно соблюсти все формальности которые написаны в статье и иметь всё равно максимально плохо читаемые коммиты вида
```feat(core): update core
Solved #123 Look also #345 #678
```
И в итоге всё равно непонятно что делалось, зачем, что это за задачи подключены.
На реальных проектах зачастую у людей либо проговариваются правила оформления коммитов, либо вообще срабатывает автогенерация текста коммита по ID задачи (т.е. в заголовок коммита прописывается ID задачи и её заголовок)
Вот эти огрызки feat, sec, refactor... что люди делают с сэкономленными буквами? Почему refactor можно написать, а feature - слишком длинно?
Огрызки, очевидно для краткости. Своего рода текстовые бэйджики. А refactor и revert полностью, потому что сокращения будут скорее всего ассоциироваться с другими словами. Сокращение ref лично для меня интуитивно подразумевает reference, то есть ссылку, а rev - revision.
А вот про практический смысл этого я бы почитал, только чтобы аргументированно было написано, без натягивания совы.
Заявки в повелительном наклонении репозиторию? - ну дичь же.
Что именно дичь? Слово "заявка" или повелительное наклонение?
Кому заявки и кому повелительное наклонение? Себе? QA (раз с твоей стороны таска закончена и ушла в CI/CD)? Кастомеру? Гитхабу? Копилоту на гитхабе?
Как я сказал уже в статье, повелительное наклонение - инструкция разработчику, себе или другому. Спасибо за комментарий
Давайте возьмем определение заявки из текста. Заявка это коммит.
Теперь разберемся с вашими вопросами. Если вы ответите сами себе на те вопросы, что задали, подставив вместо заявки слово коммит, то всё встанет на свои места. И кому коммит, и кому повелительное наклонение, и т. д. и т. п.
И мне еще не понятно, откуда вы взяли, что практического применения в использовании в коммитак повелительного наклонения нет? Я открыл гитхаб, выбрал первые попавшиеся проекты, и вижу, что в комментах коммитов используются в imperative mood.
Я дико сомниваюсь, что вы не видите такую очевидную вещь. И я предполагаю, что вы о чем-то другом можете говорить.
Мы уже много лет не отправляем патч почтой другому разработчику, чтобы он его применил к репозиторию. На этом "заявки" заканчиваются. А дальше я могу из своих коммитов автоматически нагенерить релизу changelog прям из github actions при вливании мержа в мастер или сверстать месячный отчёт для кастомера о выполненной работе. А вам для того, чтобы сделать то же самое, придётся каждый коммит переписать ручками. Вот вам два практических применения, теперь ваша очередь привести примеры практического применения imperative mood, чтобы все могли разобраться, почему стоит каждый раз мозг выворачивать прописывая "сделай" на заведомо выполненную работу. Не "дядечка в интернете или на курсах посоветовал", а вот практический кейс, который делает гит и историю, которую он хранит, ценнее
Ваш пример применим и используется только у вас. И переучивать вас никто не может. Вы заточили своюй рабочий процесс под себя. На мой взгляд, это прям круто.
Выше вам предоставили 4 ссылки о рекомендациях (сам git, соглашение о коммитах и т.д.) Они для вас не авторитет? А почему тогда ваша рекомендация должна быть авторитетной? Для нас вы "дядечка в интернете".
Я не встречал "сделай", если вы про наш язык. А вот, "fix", "add" и т. п. можете посмотреть, например в исходниках ядра линукса от Торвальдса (или и его проект для вас не авторитетен?). Вот, только там встречаются персонажи, которые не потрудились писать коммиты в одном рекомендованном стиле. Это не криминал, но выглядит как бардак. Вы всё еще против "Соглашения о коммитах"?
Ссылки в первой из которых написано "мы сами так не делаем, но вы как мы не делайте". Если что, я читал эту классную книжку и там действительно много отличных примеров как можно сделать. Но далеко не все из них вам и вашей команде действительно нужны для того чтобы инструмент приносил пользу и им было одно удовольствие пользоваться, а не дополнительную когнитивную нагрузку и срачи в команде из-за того что кто-то опять придрался к формальностям, а ревью самого коммита, по сути, так и не сделал.
Не "не потрудились", а на автомате написали в естественной форме, потому что каждый раз нужно вспоминать какие-то неактуальные правила, оставшиеся там со времён царя гороха, а не писать в нативной форме как есть. И, как видите, линукс от этого не сломался. И не только линукс.
Только что заметил, что в conventionalcommits ни слова о повелительном наклонении, хотя в примерах используют. Может, это уже и есть стандарт?
И там есть абзац "Зачем использовать Соглашение о коммитах". Правда, это применимо, если вы приглашаете других разрабов или сами участвуете в чужих проектах. Как я сказал выше, к вам это не применимо, т.к. у вас свой настроенный и возможно изолированный проект.
Давайте ссылку на RFC, если это "стандарт". Что же это за стандарт такой, если его можно не соблюдать регулярно даже в одних и тех же командах и нигде ничего не ломается.
Это в принципе так себе "применимо", не только ко мне, потому что не влияет ни на что, кроме настроения людей уверенных в том, что так должно быть. Ни на Git, ни на CI, ни на код ну никак не влияет. Вот за что действительно нужно компостировать мозг и бить по рукам, так это за коммиты вида "Fix", "Small fix", "hotfix", "sf" и прочую чепуху не несущую никакого смысла. Зато в той форме, в которой вы хотели, ага. Почему-то вот просто "Fixed" никто не коммитает - от этого коробит, потому что напрашивается текст что собственно пофикшено, а одно единственное слово "fix" - легко.
Патч не отправляем почтой. А общие правила оформления остались. Вы предлагаете изменить правила написания комментов? А надо ли?
Если вы не отправляете патчи почтой, то уже что-то поменялось. Почему бы не поменять что-то ещё? Аргументация в духе "при диалапе так страдали и сегодня надо" - ну такое
Дистры линукса тоже имеют массу проблем с путями и повторяющимся функционалом программ (арч - исключение) тянущиеся со времён царя гороха. Почему-то все до сих пор страдают. Мне кажется, к коммитам не применяется слово страдание. На питоне никто не жалуется на обязательность табов - ты не напишешь по-другому "на автомате".
Для тех кто пока не умеет у себя в проекте писать правильно, существуют рекомендации. Да и в общих открытых проектах желательно придерживаться одного стиля, чтобы не было так:
На питоне никто не жалуется на обязательность табов
Давайте я пожалуюсь: пробелы
По поводу практической стороны повелительного наклонения, в отличие от DRY, соблюдения путей и требований конкретного языка программирования, я так понимаю, у вас ничего не будет, только отговорки и несопоставимые примеры.
Приравнивать некоторые личные договорённости и рекомендации, да хоть и coding conventions, к стандартам - ну такое себе. Давайте тогда сразу ссылку на RFC?)
Обязательно нужна практическая сторона? На руби можно писать миллионами стилями, куча элиасов на одни и те же команды. Но, почему-то, народ тяготеет к одному стилю. Практика тут не причём.
Практика тут не причём
Что? Чтооооо????!
Ну вот так. Такова жизнь. Кроме практической составляющей есть ряд и других составляющих, например, влияющие на эмоциональность.
Если я в кэмл-кейсе буду писать, когда принято в снейк-кейсе, практически как-то на полёт повлияет? А если я коммит буду оформлять без двоеточия после типа коммита, а тип коммита заключу в квадратные скобки:
<тип>: <Описание>
[<тип>] <Описание>это как-то затронет весь ворк-флоу (парсерами коммитов можно пренебречь, в виду специфичности)?
Если что, я ваши сообщения не минусю. Моя оценка только в сообщениях.
Мне кажется вы сами себя закапываете. Единый стиль кода в команде принимается именно потому что это практичнее - так код других участников проще воспринимать и сопровождать. Коммиты не нужно сопровождать и регулярно вдумчиво перечитывать. К коммитам основное требование - чтобы было понятно, что там в правках происходило. Если их вот прям парсят, тогда люди сами под свой парсер как-то должны адаптироваться и договориться, ну или свой парсер доработать, но это внутрикомандный вопрос, а не некий стандарт.
Не особо парюсь о минусах
Есть конвенция о написании коммитов. Можно ее не придерживаться, но главное потом не жаловаться, что в вашей любимой библиотеке, которую вы вдруг захотели улучшить, ваш пул реквест даже не стали рассматривать на фоне оформленных "правильно" сотен других реквестов.
Дополню исходя из опыта. В репозитории хорошо иметь не только README.md а ещё и License, Authors и важно Changelog. Все коммиты должны быть связанны с Changelog историей разработки поэтому каждый коммит должен начинатся с {code-task-tracker} а если мы делаем не монолит а микросервисы то мы должны иметь общий индекс системы чтобы понимать ещё и связи {index} и того чтобы понять что это лучше взять в квадратные скобках т.к. вот так git commit -m "[SHOP-ISSUE-994] feat: добавлен вывод строки" # index = shop, code-task-tracker = issue 994 т.к. так трекер не всегда может быть частью git. И нам остаётся только в Changelog указать что мы закрыли issue 994 для shop)))) и естественно описав что изменили.
История коммитов это очень хорошо. Главное не забывать что есть ещё теги, история изменений и правила ветвления. Всё в мести при правильном использования как раз и даёт полноту картины и удобства использования.
"о химии", а не "об химии".
День добрый.
.gitignore - https://www.toptal.com/developers/gitignore/ - генератор
Git Command - https://gitexplorer.com/ - генератор синтаксиса
README - https://readme.so/ru - генератор
Не знаю на сколько актуальным будет, но может и пригодится.
Как оформить README файл
И тут же идёт пример, где после заголовков (и перед ними!) нет пустых строк.
С комментариями (зачем), которые содержат в себе весь контент, который они комментируют.
Некоторые заголовки ещё и ссылки. Местами с нарушенным уровнем вложенности.
И для полной "красоты" далее идут "блоки" кода в одну строку.
Не оформляйте так README, пацаны, на самом деле, не надо. (с)
Красота не только в коде — как оформлять репозиторий