Как я пишу коммит-сообщение
Эта тема подробно освещалась в других сообщениях блога (в первую очередь Сообщение в блоге Криса Бимса), но это важно, поэтому стоит повторить. Когда вы работаете над большим программным проектом, жизнь каждого (включая вас) становится намного проще, если вы пишете последовательные, описательные и легко читаемые сообщения коммитов.
Программная инженерия — это сложно. Вы тратите весь день (или несколько дней) на то, чтобы наметить исправление вашей функции/ошибки, написать код, отладить указанный код, написать тесты, чтобы убедиться, что в будущем ничего не сломается, а затем, после всего этого, вы должны создать ваш коммит(ы). Очень заманчиво отказаться от своей дисциплины и просто написать что-то наполовину, не задумываясь об этом, просто чтобы вы могли перевести эту задачу в состояние «Готово».
Однако вот в чем фишка: когда-нибудь вам, вероятно, придется вернуться и просмотреть это сообщение коммита. Если по какой-либо другой причине вы можете просмотреть свой репозиторий git, чтобы увидеть, чего вы достигли с момента последней проверки производительности. Просматривая журнал коммитов git, подобный этому (Да, это настоящий фрагмент из журнала коммитов, который я написал. Хуже всего то, что эти сообщения коммитов все, что есть. Ни в одном из них нет дополнительного описания):
85dd75c refactor interfaces so they are all in the same format
2af1c6d add code for branching model
d3b2606 Merge branch 'glsl'
3a6bed2 add necessary graphics libraries
d028509 fix issue #17261
2367d80 more work toward full implementation
2067b23 add cpp files
a111bff makefile generation
14a715e create repo
Это намного больше работы, чем просмотр журнала коммитов, подобного этому:
61c70bc Add a configuration to ripsaw.
8af4151 Merge pull request #7 from jwir3/jwir3/#3-cut-list
9d05854 Add a CutList data structure.
74a21ae Merge pull request #5 from jwir3/main-ui
4be2728 Add a basic user interface for binary program.
de4061d Refactor measurements functionality into its own rust file.
15cc8e1 Merge pull request #1 from jwir3/basics
a6c6010 Add the ability to create nominal and actual lumber sizes.
6a1e1fd Initial commit
я могу сказать точно что было изменено в каждом из сообщений фиксации из последнего примера.
Более того, это твоя работа. Вы потратили часы, необходимые для того, чтобы этот код заработал. Сообщение git commit — это ваша реклама проделанной работы. Это то, что увидит большинство ваших коллег, к которому прикреплено ваше имя, поскольку, поскольку мы работаем над кодом изо дня в день, мы обычно видим код, а не человека, который его написал. Гордитесь своей работой – это ваша возможность «продать» ее своим коллегам!
Правила
Я следую трем основным правилам (с дополнительным, необязательным в самом начале):
- (Необязательно) Выберите gitmoji для представления вашего коммита.
- Добавьте простое подлежащее в повелительном наклонении, начинающееся с заглавной буквы, длиной не более 80 символов и отделяемое от тела пустой строкой.
- Напишите текстовое сообщение, описывающее что было выполнено в коммите, а также почему это было необходимодлиной 80 символов, отделенных от метаданных пустой строкой.
- Добавьте все метаданные (например, номера заявок, команды CI и т. д.) в конце сообщения фиксации.
Выберите gitmoji для представления вашей фиксации
Я обнаружил, что чтение журналов коммитов (особенно однострочных журналов) можно сделать намного проще с помощью эмодзи, описывающего категорию изменений, к которой относится коммит. я лично использую гитмодзинеофициальный стандарт для того, какие типы коммитов используют какие смайлики, но вы действительно можете использовать все, что хотите, если вы последовательны.
Добавив что-то вроде 
до вашего коммита, каждый раз, когда вы его читаете, совершенно ясно, что этот коммит исправил ошибку. Я считаю, что это помогает при разборе, но вы должны быть готовы добавить несколько вспомогательных пакетов так что git log работает в командной строке.
В справочной странице для git-commitприводится следующий аргумент:
ОБСУЖДЕНИЕ Хотя это и не обязательно, рекомендуется начинать сообщение коммита с одной короткой (менее 50 символов) строки, резюмирующей изменение, за которой следует пустая строка, а затем более подробное описание. Текст до первой пустой строки в сообщении фиксации рассматривается как заголовок фиксации, и этот заголовок используется во всем Git. Например, git-format-patch(1) превращает фиксацию в электронное письмо и использует заголовок в строке «Тема», а остальную часть фиксации — в теле.
Я лично обнаружил, что 50 символов — это маловато, хотя я вижу смысл, если вы просматриваете исправления по электронной почте. Похоже, что Github обрезает строку темы коммита до 72 символов, так что об этом тоже стоит помнить. Я настроил свой редактор vim (который я использую для написания сообщений фиксации) так, чтобы он отображал вертикальную линию и автоматически добавлял новую строку в 80 символов. Это несколько произвольное ограничение, но я не думаю, что лично мне достаточно 50 или 72 символов, а ограничение в 80 символов кажется стандартом.
Я думаю, что идея ограничения в 50 символов заключается в том, что когда в терминале с ограничением длины строки в 80 символов, sha коммита и его завершающий пробел требуют в среднем 10 символов, но они может требуется до 41 символа (40 для самого sha, плюс 1 для пробела), таким образом, у вас действительно есть только 80 — 41 = 39 символов фактической длины сообщения. Однако я думаю, что большинство терминалов больше не ограничены 80 символами, так что это несколько спорно. Наоборот, это вопрос дисциплины: вы должны быть достаточно дисциплинированы как инженер, чтобы суметь обобщить ваши изменения в 50 символах или меньше.
Тем не менее, вот мой аргумент против ограничения себя 50 символами: во-первых, мы живем в обществе, которое становится все более и более приспособленным к кратким сообщениям (вспомните заголовки новостей и твиты). В большинстве случаев идеальное место для заголовка новостей составляет 60-100 символов. [^2]. 80 символов — это хорошая золотая середина в этом диапазоне, чтобы люди могли ее переварить.
Тема коммита должна быть в повелительное наклонение. По сути, это означает, что оно должно завершать предложение». Когда эта фиксация будет применена, она будет ___________________. Подумайте о том, как легко это читать, когда это правильно написано таким образом. Это также поможет вам, как инженеру, создающему фиксацию, узнать, вышли ли вы за рамки фиксации, изменяя одну связанную и связанную вещь, а не изменяя кучу вещей, которые не связаны между собой.
Еще одна деталь по этому вопросу, которая может вызвать споры: я фактически добавляю точку в конце своих сообщений о коммитах. Причина, по которой я это делаю, заключается в том, что, на мой взгляд, строка темы коммита должна быть полным предложением. Я считаю, что сообщения легче читать и анализировать, когда используются правильные знаки препинания, но это только я.
Напишите сообщение в теле
Важно добавить описательные данные относительно что, в частности, было изменено в вашей фиксации (за пределами строки темы). Я обнаружил, однако, что более важным является оправдание для этого изменения. Через полгода вы можете вернуться к этому коммиту, понять, что изменили файл или класс, а можете и не вспомнить почему это изменение было необходимо. Тело также дает вам возможность выразить себя, используя списки, маркеры, ссылки или, в некоторых случаях (в зависимости от политики вашей организации), полную уценку.
Стоит отметить, что не каждый commit требует строки темы и тела. Иногда, если строка темы абсолютно ясна, стоит просто оставить тело пустым. Я также делаю это, если это коммит слияния, но иногда я добавляю раздел метаданных, чтобы указать, кто просмотрел мое слияние:
commit a2f525f01bf657b706fd2f39bbf704aa7b9c4a69
Merge: d9f74c1fd 4530a7243
Author: Scott Johnson <jaywir3@gmail.com>
Date: Mon May 13 16:22:45 2019 -0500
Merge pull request #5616 from jwir3/bump-versions-package-may19
[r=VerteDinde, coreh]
У всех нас есть вещи, которые нам нужно добавить в коммит — номера тикетов, ссылки на другие коммиты, кто рецензировал данный коммит и т. д. Эти метаданные должны быть размещены в конец сообщения фиксации. Обоснование этого заключается в том, что это, как правило, вещи, которые требуются системе непрерывной интеграции (например, она должна быть машиночитаемой, а не человеком), или вспомогательная информация, не связанная напрямую с рассматриваемой фиксацией (т.е. если ваш коммит достаточно читабелен, зачем обращаться к оригинальному тикету за дополнительной информацией?Вы сможете найти ответ на свой вопрос в самом журнале git).
Таким образом, я склонен организовывать свои данные в коммите линейным образом, при этом информация, которая мне, скорее всего, нужна, идет первой в следующем порядке:
- К какой категории относится этот коммит
- Что меняет этот коммит
- Подробное объяснение того, что было изменено и почему это было необходимо
- Любые вспомогательные метаданные, которые помогают мне найти дополнительную информацию, если этого недостаточно.
Конфиг, который поможет вам
Я считаю, что следующая конфигурация шаблона фиксации полезна в качестве напоминания об этом. Просто поместите файл в ~/.gitmessage и он будет отображаться для вас каждый раз, когда вы входите в редактор после запуска git commit:
# When applied, this commit will:
# This change is necessary because:
# The following is metadata for this commit:
Как я могу заставить свою организацию сделать это?
Есть небольшая часть этого, которую я упустил из виду, что делает все это стоящим. Это только в некоторой степени полезно, если вы единственный в своей организации, кто делает это. Как заставить инженеров всей организации писать подобные коммиты?
Часть ответа на эти вопросы: Вы не можете. Невозможно полностью контролировать поведение других людей, поэтому вам следует умерить свои ожидания. Люди будут делать то, что, по их мнению, имеет ценность, поэтому, если они не думают, что написание сообщений фиксации таким образом имеет ценность, они не будут этого делать. Однако есть способы побудить их увидеть в этом ценность.
Я обнаружил, что около 85% организаций, в которых я работал, не имеют любой документация о том, как писать сообщения фиксации. Однако если ваша организация входит в число 15 % делает иметь стандартизированный способ написания сообщений фиксации, во что бы то ни стало, следуйте этим правилам. В противном случае я должен помнить о нескольких вещах:
Другой человек — это не ты. У них разные ожидания от начальства (и самих себя), поэтому не стоит пытаться навязать им стандарт, который вы просто создаете из воздуха.
Некоторые мелочи (например, разница между 80-символьной и 50-символьной строкой темы) являются идеологическими баталиями, за которые не стоит бороться. Если это камень преткновения между вами и коллегой, просто позвольте им делать это так, как они хотят, пока есть выгода.
Теперь о методах поощрения такого поведения. я нахожу это основной обзор и микронаграды — отличный способ поощрить написание отличных сообщений коммитов. В большинстве организаций существует некоторая форма процесса проверки кода. Это отличное место для обеспечения соблюдения практики сообщений коммитов. Однако следует быть осторожным с одной вещью: не стать слишком диктаторским. Если я увижу сообщение о коммите, которое можно было бы улучшить во время проверки кода, я часто рассматриваю возможность переписать сообщение о коммите для соответствующего человека и опубликовать его в качестве предлагаемого изменения в обзоре кода. Кроме того, не все умеют пользоваться git rebase (смотрите также Переориентация на независимость), так что стоит добавить комментарий с подробным описанием как они также меняют свое сообщение о коммите в обзоре кода.
Имейте в виду, что вы всегда можете предлагать изменение должно быть сделано, но если сообщение фиксации не Действительно не описательный, я бы обычно не задерживал проверку кода только на этом фронте. Со временем в логах станет ясно, какие инженеры тратят время на написание хорошего коммит-сообщения, а какие нет. Как только другие инженеры присоединятся к команде и будут вынуждены работать с сообщениями коммитов, которые создает другой человек, давление сверстников в конечном итоге победит.
Другой вариант, который я использую, это микронаграды. Это специфично для отдельной компании, но некоторые компании используют такую платформу, как бонус.лы чтобы сотрудники могли вознаграждать друг друга в течение месяца. Если я увижу сообщение о коммите, которое действительно выделяется в хорошем смысле, я приложу все усилия, чтобы вознаградить этого человека публично, чтобы все знали, что я ценю это.
Недостатком этого, конечно, является то, что ваша компания должна подписаться на услугу, чтобы вы могли это сделать. Однако вы можете сообщать о хороших коммитах во время ретроспективных встреч, стендапов или даже просто в Slack в удачный день, публично хваля кого-то за сообщения коммитов. Держитесь подальше от наказаний людей, которые не делать то, что вы хотите публично, так как это обычно не помогает заставить людей изменить свое поведение и обычно выставляет вас в плохом свете.
В общем, ты не можешь сила кто-то делать то, что вы хотите, но вы можете поощрять путь, который вы считаете правильным.
