Комментарии 42
Ок. Прям так и буду делать)
добавлять ID задачи;
Мигрировали таск-трекер — ура, у вас в коммитах теперь куча абсолютно бесполезных символов.
Настроить интеграцию между таск-трекером и вашим сервером реп (гитлабом, битбакетом, итд), и оставлять в пуллреквестах ссылки на задачи в таск-трекере — это полезное дело. Просто потому, что интеграция будет обозначена явно, и её затем так же явно можно смигрировать (при необходимости) на новое решение. Оставлять некие буковки в коммитах в надежде на то, что это поможет и не протухнет — это не интеграция.
в теле описания отвечать на вопросы: «Что сделали?» и «Почему сделали?»
Commit message не самое удобное место для пространных текстов. Их всегда лучше выносить в более удобную для них точку (пуллреквесты, таск-трекер, и т.д.). Я бы сказал, что ответу на вопрос "что сделали" в CM почти всегда стоит быть кратким, а ответ на вопрос "почему сделали" должен вообще появляться только в таких коммитах, которые могут выглядеть ошибочными (типа откатов, неочевидных слияний и переносов кода, и т.д.). В этом случае явно описанное "почему" помогает потом понять, что изменения были сделаны намеренно.
Статья выглядит такой себе. Прежде чем выстраивать какие-то правила относительно CM, надо начать с предпосылки: история коммитов в VСS не является таск-трекером и логом ведения разработки. И не надо натягивать сову на глобус и использовать её для этого, для этого существуют другие системы. История коммитов — это очень простая штука, приписывающая каждому изменению кода конкретного автора и некие идентификационные сведения. CM — это человекочитаемый идентификатор изменений в коде. Только и всего.
Commit message не самое удобное место для пространных текстов. Их всегда лучше выносить в более удобную для них точку (пуллреквесты, таск-трекер, и т.д.).
После минутного поиска в репозитарии ядра linux: https://github.com/torvalds/linux/commit/9becb688913023124464c5463b4389b3b293f0e7
Вроде достаточно длинно. И неплохо помнить, что оригинально PR и был коммитом вместе со своим commit message - он почтой уходил тому, кто должен его замержить.
У репозитория linux своя атмосфера, там CM используется в качестве писем принимающему пуллреквесты.
То есть да, они так живут. Насколько это удобно — большой вопрос.
Я подозреваю, что разработка через списки рассылки может быть довольно удобна, хоть и непривычна почти всем.
А уж с точки сохранения той самой старой истории разработки - так практически самый надежный вариант, как я понимаю. У них архивов этой самой переписки - за *-тцать лет есть. В случае чего делаешь полнотекстовый поиск по тем архивам и находишь, чего это мы тут наделали много лет назад. А не жалеешь, что оно умерло где-то в недрах очередной project management софтины, вендора которой уже не существует.
Ну да, в этих условиях оно наверное неплохо.
Но вот если глянуть на кровавый энтерпрайз, то там скорее наоборот всё. Project management-софтина живёт себе десятилетиями, а вот в репозиториях настолько же чехарда, как и собственно с проектами — образовался новый проект, и в его репозиторий тут же через ctrl+c/ctrl+v бахнули слегка видоизмененный (а то и не измененный) код проекта-предшественника, и поехали фигачить дальше. В этих условиях искать правды в коммитах вообще не приходится.
Вы в гугле-то с гарантией не найдете ничего старше 10 лет. Чтобы найти — нужно помнить, какие там были ключевые слова, а это далеко не так очевидно. У нас в jira было порядка 4000 задач — разбили проект на три, сейчас в новом проекте за полтора года примерно 700, найти что-то, что не помнишь точно — уже не просто, проще просмотреть все 700 (хотя бы названий). И это проект где 3 (три) программиста.
Вот потому он и там такие простыни и пишут. Плюс Jira довольно плохо ищет, плюс туда, если специально этим не заморачиваться (все письма всех заинтересованных лиц в не копируем?), попадает далеко не весь контекст.
У нас на небольшом таком почти легаси энтерпрайзе лет 8 возраста прямо по ней тоже достаточно плохо искалось. Постоянно приходилось в архивы переписки погружаться, чтобы понять, почему и для чего захотелось что-то сделать и чем это кончилось.
Мигрировали таск-трекер — ура, у вас в коммитах теперь куча абсолютно бесполезных символов
Хе, как-то пришлось из бекапа старый трекер поднимать, чтоб найти почему же там написана такая … такое … что-то совсем странное ☺️
Нет, из всего это самый важный момент - все можно простить, но к трекеру привязаться нужно
Добавлю. Используем правила semantic-release, ну и собственно сам https://github.com/semantic-release/semantic-release
Что-то типа
feat(JIRA-123): Implemented ...
fix(JIRA-100500): Fixed ...
Что позволяет еще и автоматически генерировать Version и Changelog
Как я понимаю, ноги у правила растут из проектов, куда поступает много PR, где сидит такой условный Линус, и решает, принять ли ему фичу «Оповестить slave-устройства», «Исправить ошибку загрузки из БД» или не принимать. В заголовке коммита — действие, которое применится к проекту при мерже.
Но совсем другое дело во внутренней разработке. Там принятие коммита — дело решённое (свои коммиты никто не будет реджектить). Там при работе с логом коммитов имеем дело со свершившимся фактом: «Реализовано оповещение slave-устройства», «Исправлена ошибка загрузки из БД». И так читать и понимать намного проще, когда понятно, что в версии 1.x.x сделано то или это.
ИМХО.
Согласен. На практике часто регламентируют действие в зависимости от типа коммита, чтоб можно было легко автоматичкски сделать change log или release notes (см. комментарий выше).
Например так: Добавлено …, Исправлено …, Изменено …., Удалено …
Для русского — можно не следовать, т.к. выигрыша между Добавить и Добавлено почти нет
Коммит редко попадает сразу в мастер. Сначала производится рецензирование.
Поэтому повелительное наклонение как раз максимально уместно. Мы пишем рецензенту о том, что предлагается сделать этим коммитом.
Инфинитив это тоже форма повелительного наклонения. Вполне себе приказной тон: «Всем лежать полчаса!».
И ещё такая форма общепринята в локализации, например названий пунктов меню.
Save... → Сохранить...
Рецензент читает это сообщение 5 секунд, а потом оно хранится в истории вечно. И например может использоваться как основа для листа изменений, в котором видимо всё таки должны описываться уже внесенные, а не планируемые изменения.
Причем для рецензента в принципе без разницы будет в сообщении "Добавить кнопку" или "Добавлена кнопка". Первый вариант обычно проще, потому что в такой форме описывается исходная задача и можно просто скопировать название задачи и не париться. Плюс в английском языке такие глаголы короче. Но в русском языке и с точки зрения последующего использования истории, на мой взгляд, второй вариант единственно возможный.
https://habr.com/ru/post/416887/
уверен, если поискать, ещё статьи с теми же советами найдутся
Я в своих проектах прошу просто копировать загаловок таски из таск-трекинга (Jira, Youtrack -- неважно). Выглядит, +- лапоть
{аббревиатура проекта/модуля/...}-{номер таски} {одно предложение описания}
e.g. GD-007 Send e-mails with list of files and links to folders
Многие системы умеют к подобным каментам цеплять билды, таск-треки, код-ревью, прочая, прочая, прочая. Опять же, многие системы позволяют копи-пастить этот текст, чтобы не перенабивать его. Его же легко гененировать при автоматизации некоторых процессов.
Опять же, все обсуждения проблем, документация, прочая -- выносится в таск-тракинг и в документацию, а не в коммит мессаджи (ядро линуха выводим из обсуждения).
Опять же, в зависимости от системы бранчевания, можно настроить соответствующим образом мёрджи. И, скажем, feature branch будут мёрждится с нужным каментом.
Много, что можно и как сделать. Главное -- команде договориться и следовать этому принципу.
0047514 Устранить ошибку загрузки из базы данных
Эти комментарии однородные и понятные.
Это автору так кажется. Они понятные, пока у вас одна ошибка загрузки из базы данных была в проекте. Как только их будет примерно две, они перестанут для вас выглядеть как одинаковые, и такой текст ничего вам не скажет. Даже завтра. А уж что будет через год — вообще сложно представить.
хорошо бы раскрыть мысль, почему нужно использовать английский язык, а не какой-то другой? кажется, это требует знания английского от разработчиков в достаточно приличном качестве, иначе будет мгимо финишд
Я одновременно согласен и не согласен
Зависит от
В целом это хороший тон, но мне встречались ситуации, когда большая часть команды, работающей с репозиторием не владеют им достаточно (геймдизайнеры в игровом проекте)
В этом случае оказалось разумным описывать комментарии на русском
Git используют не только программисты. Например, проектом может быть книга на разных языках.
А вы считаете что если широко известные всем рекомендации повторить еще много раз - они станут лучше что-ли? На автора напали в общем именно за то, что ничего нового тут нет. Ничего особо плохого впрочем тоже. Если соблюдать эти правила - хуже не будет (но свое время вы потратите зря).
Именно поэтому и важно говорить на эти темы.
вы считаете, что писать достаточное для понимания сути коммита описание — это подменять таск-трекер?
извините, но я не хочу каждый раз по результатам git log или git blame лезть в таск-трекер. вот если мне надо будет копнуть глубже, то да, там могут оказаться бесценные обсуждения, приведшие к получившемуся решению (а могут и не оказаться).
да и вообще, как можно таск-трекер заменить историей коммитов? чуть ли не основное в трекере — это то, что ещё не сделано, а этого нет в истории коммитов по определению.
У нас в компании свой подход к организации коммитов. Для каждой полноценной задачи мы создаём от HEAD новую ветку с названием, включающим код задачи и его краткое название. Например, T4C-401__order-creation. Откуда T4C - название проекта, 401 - код задачи, __ - просто разделитель, а order-creation - краткое описание задачи. Так проще ориентироваться по веткам. Коммиты делаются не по завершению рабочего дня, а по завершении задачи. Именуются коммиты таким образом:
fix: Невозможность закрыть модалку GetPrice
upd: Обновлен React до версии 18
ref: Переписан легаси код в <название файла>
Страница списка товаров (Либо "Добавлена страница списка товаров")
В начале названия коммита один из префиксов:
fix - фикс ошибки, ref - рефактор, реорганизация кода, upd - поднятие (обновление) пакетов. Если префикса нет, значит, было просто добавление нового функционала. В описании комита пишется либо пояснение к текущей задаче, либо какие-то дополнительные мелкие правки, которые были сделаны в ходе работы.
Такой подход лично нам достаточно неплохо упрощает навигацию по репозиторию проекта
комментарии типа «03.03 – 04.03» или «последняя правка» не дают ничего, кроме чувства досады на себя в прошлом.
никаких чувств досады.. зачем смотреть на старые коммиты? чтобы что?
Что делали со второго по седьмое число? Кто такие Вася и Елизавета? Остаётся закатить глаза, как Роберт Дауни-младший в меме, и идти перекапывать все детальные описания и задачи в таск-трекере.
Зачем закатывать глаза? Зачем знать кто такие Вася и Лиза? зачем знать что делали со второго по седьмое число? чтобы что? Вот, допустим, новый разработчик на проекте. Пришла старая задача\баг. Именно в таст-трекере и необходимо начинать искать "концы" и все обсуждения, принятые решения, ответсвенных за задачу, продактов и т.д.. и там же и продолжать общение.
Корректный комментарий к коммиту ― это один из способов эффективной коммуникации в команде
Гит и коммиты - это как источник истины\база\хранилище\блокчейн если угодно, а коммиты - типа миграций что-ли. Но точно уж не для чтения глазами истории проекта или "коммуникаций".. имхо.
Если при этом приходится по несколько часов в неделю разбираться с непонятными коммитами
Зачем разбираться с непонятными коммитами? Разбирайтесь с мерж-реквестами вцелом на этапе ревью.. в контексте какой-то текущей задачи. Зачем "разбираться" со старыми непонятными коммитами?
Написать хороший комментарий ― это способ сэкономить время и себе, и коллегам,
Это способ ещё больше потратить мыслетоплива на ровном месте.
Если это звучит очевидно, то странно, почему в репозиториях до сих пор часто творится неразбериха.
Возможно потому, что необходимость в красивых коммитах - это ложь? Культ "красоты коммитов" навязывается всё жизнь благодаря статьям.
Ейбогу. Допустим есть два проекта - проект-А с "красивой" историей комито. Проект-Б - с "некрасивой" историей. Какая к чорту кому разница на практике?? Я понимаю, что иногда удобно черри-пиком какой-то коммит вырезать\вставить, но обычно ведь это и происходит для мелких "непонятных" коммитов, часто в локальных рамках одного разработчика, который помнит что и где.
Цитата моего старого комментария по всему этому поводу:
Всегда интересовал этот культ чистой истории коммитов. На практике. Чем чистая история лучше нечистой истории с кучей fix/merge коммитов? Какие реальные случаи.. на практике.. были, чтоб вот чистая история как-то реально помогла.То что там всё чисто, и понятна история развития проекта.. это ясно. Я тоже за всё хорошее, и против всего полохого. Но на практике.. есть ли кому какое дело до чистой истории коммитов?
"Потом смотришь на эту паутину в истории и глаза начинают кровоточить."
Так можно просто не смотреть в эту историю. Зачем туда смотреть?)
Git - как источник истины и как хранилище - ок. Но как чтение истории проекта - зачем? кому оно надо? Пойди почитай релиз-ноутсы если на то пошло)
В небольших командах и так понятно кто какой кусок делает - и где чей залёт можно выяснить простым совещанием. В огромных командах, мне кажется, тем более всем плевать на историю проекта в контексте чтения коммитов в git-е.
Я без наездов, просто действительно культ чистой истории коммитов мне непонятен.. как-будто её кто-то читает.. ейбогу.)
История - это то что уже прошло, здесь и сейчас она не нужна, искать виноватых смысла нет, двигайте проект вперёд)
Я конечно сильно извиняюсь, но или вы не работали в серьезных командах или просто троллите нас
никаких чувств досады.. зачем смотреть на старые коммиты? чтобы что?
Чтобы знать что Ваш коллега сделал, какие шаги предпринял
Вот, допустим, новый разработчик на проекте
Именно поэтому и не только надо документировать свои шаги
Но точно уж не для чтения глазами истории проекта или "коммуникаций".. имхо
Вот тут явно видно что Вы никогда не работали в больших и серьезных командах
Зачем разбираться с непонятными коммитами? Разбирайтесь с мерж-реквестами вцелом на этапе ревью..
Если все будут делать свою работу правильно то и не надо будет будет разбираться с непонятными коммитами
Какая к чорту кому разница на практике?
Разница огромная, одно дело работать в команде где все не только делают свою работу но и передают информацию другим что и как сделано. А другое дело работать в команде где часть разработчиков слишком самодовольны, считают себя выше других и не считают своей обязанностью информировать своих коллег о проделанной работе
Вы также поделились своими старыми комментариями на эту тему. Очень жаль видеть что вы никак не поменяли свое отношение к этой теме.
зачем смотреть на старые коммиты? чтобы что?
Лет через пять-десять в процессе очередной доработки смотришь на кусок кода и не понимаешь зачем и почему оно что-то делает. В идеале - ты читаешь коммит на интересующие строчки и понимаешь. На практике, когда номера issue из таск-трекера расставлены и этот таск трекер еще доступен - смотришь по этому номеру там. Но с этим могут быть проблемы, потому что код может быть унаследован от другой компании и в ее таск-трекер доступа нет, от самого таск-трекера уже могли отказаться, а данные смигрировать не смогли.
Зачем "разбираться" со старыми непонятными коммитами?
Вот поэтому. Потому единственно, что может быть в наличии, когда надо понять, для чего это все тут натворили - это коммиты.
Пришла старая задача\баг. Именно в таст-трекере и необходимо начинать искать "концы" и все обсуждения, принятые решения, ответсвенных за задачу, продактов и т.д… и там же и продолжать общение.
хотя бы затем, что есть git log, есть git blame, вместе с вменяемыми commit message это позволяет быстро разобраться в 99.99% случаев. а в 0.01% да, есть смысл читать развесистые истории обсуждений.
@azizoid
Честно не троллю. Просто действительно на практике не вижу реальной ценности в развесистых коммит-сообщениях, или там написанных по какому-то паттерну. Я понимаю - что программисткая сущность пытается всё упорядочить и сделать код\коммиты красивыми и стройными. Работал в разных коммандах по уровню "серьёзности". Так или иначе, внутри всегда есть мини-команды по 4-5 человек. Не было такого чтоб над одним куском функционала работало по 20 человек. Где-то была "красивая коммит-история по правилам", где-то нет. Точно одно - это никак не влияло на решение проблем и продвижение проекта вперёд.
Ну вот не вижу юзкейсов, когда нужно смотреть в годичную историю коммитов.. и на основании этого принимать какие-то решения.. или упасигосподи blame-ить кого-то за написанный давно код.
Давайте рассмотрим парочку примеров.
Пример-1.
Проекту пару лет. Приходит новый разраб. Ему дают новую задачу или починить древний баг. Вижу только одну причину, чтобы он глянул историю коммитов - чисто ради интереса прикинуть интенсивность работы на данном проекте, посмотреть принятые конвекции по именованию коммитов, посмотреть возраст проекта. А так.. зачем ему вникать(!) в историю коммитов? читать их.. что с того? Есть текущий срез состояния проекта.. двигай его вперёд, решай проблемы, оставляй после себя лучше чем было (принцип бойскаута).
Пример-2.
Проекту пару лет. Есть сформированная команда 3-5 чел, которые его пилят. Есть "старший" проекта, который ответственный за раскидывание тасок и принятия финального решения при спорных моментах. Разраб-1 пилит один кусок функционала. Разраб-2 совсем другой кусок. Появляются мерж-реквесты. Каждый ревьюит (ака кросс-ревью) открытые МР-ы. Как только есть два апрува - заливаем. Где, в каком месте, на каком этапе кому-то может понадобится годичная история коммитов? Есть ли есть где-то чей-то провтык, пролезло мимо ревью.. то обычно и так понятно с кого спросить.. так как все находятся в контексте происходящего. Нестандартные, неочевидные, нелогичные вещи, или явно "плохие распоряжения сверху" - фиксируются в коде комментариями, плюс описываешь это в таске на всякий случай.
Лет через пять-десять в процессе очередной доработки смотришь на кусок кода и не понимаешь зачем и почему оно что-то делает.
хотя бы затем, что есть git log, есть git blame, вместе с вменяемыми commit message это позволяет быстро разобраться в 99.99% случаев
С каким-то древним легаси поможет разобраться обычно только "хранитель знаний" (разработчик или продакт) который ведёт проект сначала. Надеятся на древние коммит-сообщения нет смысла.. мы же не знаем при каких обстоятельствах был написан код, какие были условия задачи и ресурсы. Но бывает что такого "хранителя знаний" нет. Тогда непонятный кусок кода - можно постараться понять и отрефакторить, в идеале удалить, или не трогать. Так или иначе - это и есть процесс погружения в проект.
Мой поинт в том, что есть текущий срез состояния проекта. Отталкивайся от него, и обращайся к людям которые есть в компании и что-то знают сейчас. Смысл копошиться в истории коммитов разработчиков(!).. это ж история.. то что уже прошло.. зачем тратить энергию.. надо забыть и двигать проект вперёд, решать текущие проблемы. Зачастую пообщаться ртом вживую с людьми даёт намного больше, чем древние коммиты нонеймов, которые в тот момент думали по-своему.
это ж история.. то что уже прошло..
Поправка. Оно не история. Оно эксплуатируется... Вот только уже никто не знает, актуально ли оно текущим условиям и вообще почему кому-то могло потребоваться, что каждую 17 неделю клиенту с буквой 'зю' на 5-ой позиции в имени мы отказать в обслуживании должны. И как именно мы пострадаем(и пострадаем ли), если отказывать перестанем.
И все вот эти советы про коммиты - это как раз про то, как сделать так, чтобы эти знания хоть как-то сохранились. Сохранять, естественно, нужно не только в коммитах. А еще и в комментариях, issue трекере, архиве почты, всяких ТЗ и не очень. Везде-везде. Чем больше мест, куда мы это записывали и кросс-линковали между собой - тем больше вероятность, что потом получится ниточку потянуть и утерянное тайное знание восстановить.
А по поводу 'решать текущие проблемы' - на этот счет хорошая страшилка есть (наверняка художественно преувеличенная) - 'Institutional Memory and Reverse Smuggling'
Или не очень преувеличенная:
Про британскую почту(Wikipedia)
Небольшая PDF-ка про баги написанная в процессе разбирательств.
Вот на что угодно могу поспорить, что сильно здоровая часть, почему все это вовремя не чинили - это потому, что никто уже и не знал, как этот черный ящик работал и поэтому ничего не трогали, чтобы еще сильнее не сломать. А последнюю PDF-ку, она хоть и на толстенная на английском легалайзе, но очень рекомендуется к прочтению(как ни странно, там все достаточно понятно)
И в этой аргументации - почти все про разработку, т.е добавление/изменение функционала. А системы пишутся для того, чтобы их эксплуатировать. Т.е. где-то рядом еще и люди последней линии поддержки сидят. Которым куда-то со стороны пользователей прилетает issue 'нам тут кажется, что происходит то, что не должно происходить'. И вот тогда - частенько начинаешь копошиться во всем, до чего можешь дотянуться, пытаясь понять, что тут произошло, делает ли оно то, что оно должно (предположительно) делать и правильно ли это.
У нас в команде например проблема с написанием тикетов, и я все ругаюсь с ними чтобы нормально писали таски. Как-то мне пришел тикет который состоял из одного скриншота. Даже заголовка не было. Такие Тикеты я сразу возвращаю во вкладку заблокированные или черновики. Обязательно сообщаю об этом в утреннем стандапе
8 правил, которые пригодятся при описании Git-коммитов