Как оформлять коммиты, чтобы потом не было больно

[Rathil]

Я с телефона, извините, не могу ЛС написать.
Измените с " Как оформять коммиты, чтобы потом не было больно"
На «Как оформлять коммиты, чтобы потом не было больно».

[AllRight88]

Спасибо, исправил! До заголовка спеллчекер не добрался :)

[ashumkin]

очень мне нравятся в этом плане исходники самого Git:
бывает,

в файле изменена одна строка, а коммент - простыня на 20 строк

git log -1 -p d69360c6b17d1693a60b9f723a3ef5129a62c2e5"

commit d69360c6b17d1693a60b9f723a3ef5129a62c2e5
Author: Ben Walton <[e-mail]>
Date:   Mon Dec 22 15:25:44 2014 -0800

    t0090: tweak awk statement for Solaris /usr/xpg4/bin/awk
    
    The awk statements previously used in this test weren't compatible
    with the native versions of awk on Solaris:
    
        echo "dir" | /bin/awk -v c=0 '$1 {++c} END {print c}'
        awk: syntax error near line 1
        awk: bailing out near line 1
    
        echo "dir" | /usr/xpg4/bin/awk -v c=0 '$1 {++c} END {print c}'
        0
    
    Even though we do not cater to tools in /usr/bin on Solaris that
    have and are overridden by corresponding ones in /usr/xpg?/bin,
    in this case, even the XPG version does not work correctly.
    
    With GNU awk for comparison:
    
        echo "dir" | /opt/csw/gnu/awk -v c=0 '$1 {++c} END {print c}'
        1
    
    which is what this test expects (and is in line with POSIX; non-empty
    string is true and an empty string is false).
    
    Work this issue around by using $1 != "" to state more explicitly
    that we are skipping empty lines.
    
    Helped-by: Jonathan Nieder <[e-mail]>
    Signed-off-by: Ben Walton <[e-mail]>
    Reviewed-by: Jonathan Nieder <[e-mail]>
    Signed-off-by: Junio C Hamano <[e-mail]>

diff --git t/t0090-cache-tree.sh t/t0090-cache-tree.sh
index 067f4c6..601d02d 100755
--- t/t0090-cache-tree.sh
+++ t/t0090-cache-tree.sh
@@ -22,7 +22,7 @@ generate_expected_cache_tree_rec () {
    # ls-files might have foo/bar, foo/bar/baz, and foo/bar/quux
    # We want to count only foo because it's the only direct child
    subtrees=$(git ls-files|grep /|cut -d / -f 1|uniq) &&
-   subtree_count=$(echo "$subtrees"|awk -v c=0 '$1 {++c} END {print c}') &&
+   subtree_count=$(echo "$subtrees"|awk -v c=0 '$1 != "" {++c} END {print c}') &&
    entries=$(git ls-files|wc -l) &&
    printf "SHA $dir (%d entries, %d subtrees)\n" "$entries" "$subtree_count" &&
    for subtree in $subtrees

Вот это — искусство, а не «ваши»:

git commit -m "Update homepage for launch"

;)
*как по мне, это плохой пример*

P.S. Вы бы прогнали статью через спеллчекер, уж больно много опечаток

[AllRight88]

Да, зря на вычитку понадеялся. Прогнал, все исправил, спасибо!

[Lol4t0]

Все зависит от изменений. Что вы напишете к коммиту с исправлением опечатки Nmae на Name?

[ashumkin]

я-то так и напишу, но приводить для примера в статье, озаглавленной «Искусство коммита» («The Art of the Commit»), не стал бы :)

[Lol4t0]

Хорошо, как правильно написать? Написать сочинение по изменению, которое исправляет серьезный баг горзадо проще, чем по такой мелочи.

[ashumkin]

Не думаю, что стоит впадать в крайности и описывать зачем исправлялась опечатка :) По-моему, это вещь очевидная и текста
Исправить опечатку: имя локального параметра должно быть Name, а не Nmae
кажется, вполне хватит.
Но и я придерживаюсь мнения, что писать «сочинение» писать нужно не только по серьёзным багам. Стоит всё же думать о том, что то, что понятно сегодня, может быть (и будет) забыто и непонятно самому себе через месяц/полгода/год, а другим и то вовсе непонятно.

[Lol4t0]

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

[Randl]

Хм, а зачем? Текста

Исправил опечатку

по-моему хватит. Если интересно какую именно (с чего бы?), смотрим диффы.

[ashumkin]

ну, меня не убудет написать какая именно опечатка была исправлена

*и мне кажется, эта информация может быть полезна для околоконтекстного поиска, когда она является опорной для поиска других изменений…

[Regis]

А по мне вся эта простыня — плохой пример.

Этому тексту самое место в багтрекере, как мне кажется.

[Lol4t0]

Почему бы ему не быть и там и тут? Чтобы быстро оценить ситуацию все равно удобнее сомтреть git log --oneline

[ashumkin]

не согласен

метаданные к изменениям кода должны быть там, где они управляются — в SCM
зачем в описании ошибки (в багтрекере) — описание того, как и зачем меняется код?
кроме того, ошибка может затрагивать несколько версий продукта, несколько его платформ, etc

развивая тему:
при работе с историей кода, лезть ещё в багтрекер (и хорошо ещё, если с ним есть интеграция), сопоставлять даты комментариев (вы же в комментАриях будете писать как вы меняли код?) с датой самого коммита? нет, увольте…

[Regis]

В IDE типа JetBrains IDEA — все перечисленные вами вещи (в частности сопоставление изменений и строк) делаются за пару кликов. Совершенно не проблема.

[ashumkin]

Ну, каждый о своём… не у всех IDE — IDEA

[MANIAK_dobrii]

Тут помогает разумное использование трекера задач и чего-то вроде git-flow, когда на каждую таску есть ветка. Лень никто никогда не отменят, даже у самых занудных разработчиков, себя я спас от приступов лени, написав pre-commit скрипт, который из названия текущей ветки выдирает айди задачи в таск трекере и прилепляет перед сообщением.

На самом деле многое зависит от команды и проекта, но, в целом, в статье рекламируется отличная практика.

[michael_v89]

Не пишите что поменялось — это всегда видно по диффам

Думаю, писать что поменялось тоже нужно. Это полезно, когда надо найти конкретный коммит из разряда «точно помню, что-то где-то я такое делал», или точную дату изменений. Смотреть дифф каждого коммита утомительно. А подробный ответ на вопрос зачем обычно есть в таск-трекере. Я обычно пишу как в последнем пункте — «что и зачем я сделал» в сжатом виде. А так со всем согласен, правильно написано.

[tyomitch]

Найти коммит, когда известно, что поменялось, помогает git blame.
Так что ещё и в commit message это вписывать незачем.

[michael_v89]

Код может несколько раз измениться, или вообще быть вынесен в другой файл.

[tyomitch]

Аргументом для git blame можно указать любую историческую версию.

[ashumkin]

а вот как раз чтобы найти эту историческую версию, надо прошерстить git log
)))

и хорошо, если можно использовать git log -S/-G
(если помнишь что именно изменялось)
а при указанном подходе — почти точно поможет git log --grep


впрочем, тогда git blame уже будет не нужен

[LeXuZZ]

Для плохих коммитов есть github.com/jayphelps/git-blame-someone-else :D

[cemick]

Не знаю, что в книге, но в выжимке капитанство. В принципе это давно стандарт, например, вот правила на которые мы ориентируемся kernel.org

Хотел бы только добавить, что важно писать не только «зачем», но и «мотивацию». Между «зачем» и «мотивация» на самом деле большая разница. Из мотивации можно выяснить точку зрения автора коммита. Часто бывает неочевидно, почему для решения был выбран именно «вот такой» подход. Дам ссылку на наш опыт насаживания подобного подхода написания текста коммитов Что дал переход с SVN на Git или Git как ключ для синергии хороших практик

[seregamorph]

Небольшой оффтоп.
Долгое время сидели на gerrit (обертка над git), его идеология отличается от github-подобных систем тем, что один смысловой changeset — это один коммит, если есть правки после ревью, делается amend/squash, а ревью идет между ревизиями одного changeset. После ревью в основную ветку попадает ровно один коммит.
Так вот это я к тому, что когда изменения по одному тикету размазаны на несколько коммитов, очень неудобно смотреть лог, когда подряд идут коммиты с одним именем, скажем «PROJ-123 fixsmth».

[ashumkin]

я в случаях, когда тикет размазан по нескольким коммитам, пишу
issue #N: бла-бла
issue #N: бла-бла-2
и последний коммит уже
fixed #N: <summary>
(и если их больше двух, то обычно вливаю в master с --no-ff)

[BalinTomsk]

Пройдя через несколько крупных компаний пришел к такому темплейту:

JIRA 3718: Service failure with error: 0x0023 — Add guard to check pointer — номер тикета, его заголовок и что сделано в сабмите.
to CL2012 (main), 2021(release 1.1.3), 2023(accepted 1.1.3) — Если была интергация/merge в другие ветки, то номера всех изменений и номера изменений связанных с этим тикетом.

Codeline: 1.1.5 — версия продукта, для которого было сделано изменение

Code review: 4023 — номер преревью, где само изменение было обсуждено, с другими девелоперами и отвественными работниками

Problem: Service failed because pointer was not verified.

Fixed: Add guard to check pointer

Tested:
— Created database
— Run Server
— Pass all unit test

Docs: www.company.com/KB45034

[berman]

Простите, снова не выдержал.

[ashumkin]

удачи в командной разработке или вхождению в новый (для Вас) старый проект, который «оформлялся» подобным образом

[berman]

Так я не спорил с вашей статьей и поддерживаю вас, сам стараюсь писать полноценно. (Просто смешную пикчу запостить не выдержал)

[ashumkin]

JFI: статья не моя ;)

[Myshov]

Еще есть такая забавная штука :)

git commit -m '$(curl -s http://whatthecommit.com/index.txt)'