Время, когда у вас на диске был файл архива под названием «версия 1», должно быть далеко. Бьюсь об заклад, вы используете какой-нибудь инструмент для контроля версий, например GitHub. Таким образом, вы должны писать коммиты каждый раз, когда хотите добавить свой код в проект. Вы когда-нибудь задумывались, хороши ли ваши сообщения о коммитах? Возможно, вам не нравится их писать, и вы удивляетесь, почему вы должны делать это каждый раз, когда хотите отправить код. В конце концов, разве изменений недостаточно?
Эта статья поможет вам создать хорошее сообщение коммита. Это даст вам (для меня) хороший образец, чтобы увидеть с первого взгляда, что произошло в этом сообщении коммита.
Почему сообщения коммитов важны?
Итак, достаточно ли изменений? По моему (и, надеюсь, многим другим) мнению, нет!
Но почему?
Сообщения фиксации имеют множество применений. Это первый способ общения с вашими коллегами-разработчиками по проекту. Изменение определяет, как вы чего-то достигаете, но сообщение фиксации объясняет, почему вы это делаете. Он должен давать достаточно контекста, чтобы участник не задавался вопросом, почему какой-то код написан именно так. С правильными объяснениями вы не будете тратить драгоценное время на то, чтобы спрашивать себя, почему разработчик вставил этот код. В некоторых случаях, таких как проекты с открытым исходным кодом, занятые сопровождающие даже не будут читать ваш код, если вы не предоставите им минимум информации, например, красиво написанное сообщение о коммите.
Питер Хаттерер писал:
Любой программный проект — это совместный проект. У него есть по крайней мере два разработчика, первоначальный разработчик и первоначальный разработчик через несколько недель или месяцев, когда поток мыслей уже давно покинул станцию. Питер Хаттерер(opens new window)
Подводя итог, он расскажет нам:
«Сообщения фиксации предназначены не только для ваших коллег, но и для вас в будущем, как Питер Хаттерер»
Проект предназначен для поддержания в долгосрочной перспективе. Иногда спустя годы после того, как кусок кода был написан, вы можете спросить себя, почему он был написан именно так. Это случилось со мной на этой неделе с функцией, которую я написал всего 6 месяцев назад. С хорошо написанным сообщением о коммите легче вернуться в то состояние, когда вы писали это изменение.
Забота о сообщениях коммитов также может упростить вашу повседневную жизнь. Некоторые инструменты становятся более интересными благодаря значимой истории коммитов, например, несколько git-команд log, rebase, cherry-pick, … Когда вы возвращаетесь из праздники простой журнал git — красиво даст вам много информации о том, что ваши коллеги делали, пока вас не было. Написание хороших сообщений о фиксации вынуждает вас разделять изменения, что упрощает просмотр с помощью git log -p.
Говоря о проверке, вам когда-нибудь приходилось перебазировать свой код на какие-то изменения, внесенные разработчиком? Становится легче понять, почему было внесено изменение, если сообщение о коммите имеет реальный смысл. Это делает результаты перебазирования более предсказуемыми. Другой пример — команда git fault, которая, кстати, предназначена не для того, чтобы высмеивать ваших коллег, а для того, чтобы дать вам контекст для конкретной строки кода. Это может быть очень полезно, когда вы хотите реорганизовать часть кода.
И последнее, но не менее важное: хорошо структурированная история коммитов позволяет создавать журнал изменений между двумя версиями вашего проекта, чтобы информировать ваших пользователей об изменениях.
Это огромное количество причин, чтобы начать уделять время написанию хороших сообщений коммитов.
Как написать хорошее сообщение коммита
Теперь, когда вы убедились, что сообщения коммитов важны, давайте поговорим о том, как их писать.
Например, эти сообщения фиксации не согласованы, что затрудняет их чтение.
fixex bug #72
did some perfomance stuff
Remove built files
Add tests #81
hope it work
forgot filesСтиль. Синтаксис разметки, перенос полей, грамматика, заглавные буквы, пунктуация. Распишите эти вещи по буквам, избавьтесь от догадок и сделайте все как можно проще. Конечным результатом будет удивительно последовательный журнал, который не только приятно читать, но и который действительно читается на регулярной основе. Содержание. Какую информацию должно содержать тело сообщения фиксации (если таковое имеется)? Чего он не должен содержать? Метаданные. Как следует ссылаться на идентификаторы отслеживания проблем, номера запросов на вытягивание и т. д.? Крис Бимс — Как написать сообщение Git Commit(opens new window)
В приведенном выше примере мы видим, что некоторые коммиты перепутаны, потому что значение было распространено более чем на один коммит. Чтобы предотвратить это, Крис говорит, что должен существовать шаблон коммита, который соответствует 7 правилам, чтобы написать хорошее сообщение коммита.
- Отделите тему от тела пустой строкой
- Ограничьте строку темы до 50 символов
- Заглавная строка темы
- Не заканчивайте строку темы точкой
- Используйте повелительное наклонение в строке темы
- Оберните тело в 72 символа
- Используйте тело, чтобы объяснить, что и почему по сравнению с тем, как
Я лично применяю подмножество этих правил:
- Ограничьте строку темы до 48 символов
- Заглавная строка темы
- Используйте повелительное наклонение в строке темы
Мало того, что персонаж ограничен, чтобы заставить вас быть кратким, что является отличным навыком, он также хорошо сочетается со многими инструментами.
Я склонен думать, что лучшее — враг хорошего. Вот почему я не стал говорить о теле сообщения коммита. Я думаю, что у нас достаточно работы по итоговой строке. Но я бы добавил еще одно правило:
- Добавьте идентификатор заявки или задачи
В большинстве случаев мы используем инструменты для обсуждения в процессе проверки кода, такие как GitHub или Azure DevOps. Вся информация об изменении будет как минимум описана там. Я добавил это правило об идентификаторе отслеживания, чтобы было проще находить связанные запросы на включение/слияние. Написание тела коммита лучше, чем добавление идентификаторов отслеживания, потому что, если вы измените свое решение менеджера репозитория, вы потеряете всю эту ценную контекстную информацию, а ваши идентификаторы отслеживания станут бесполезными.
Вот пример истории коммитов с применением этих правил
Make core independent from the git client (#171)
Upgrade Docker image version (#167)
Add maven preset (#172)
Add a generic preset using configuration file (#160)
Improve error messages for preset system (#161)
Publish Canary version on master push (#141)Последовательный стиль значительно облегчает чтение. Вы можете выяснить контекст изменения, вы также видите, если возможно, примененный Тикет. Самое главное — найти общие правила в вашей команде, чтобы иметь хорошо структурированную историю коммитов. Для этого есть некоторые соглашения, которые могут помочь вам найти их, но мы вернемся к этой теме позже.
Если вам трудно понять, какое сообщение вы должны написать, возможно, вам следует разделить коммит на более мелкие части. Питер Хаттерер перечислил в своей статье несколько примеров, когда трудно найти хорошее сообщение коммита, потому что ваш патч коммита может быть нелогичным.
Обязательные соглашения
Как было сказано ранее, вы должны определить соглашение о фиксации (возможно, для вашей команды или всего отдела разработки). Существует множество соглашений о коммитах с открытым исходным кодом, которые могут быть хорошим источником вдохновения. Они также поставляются с целой экосистемой, которая включает в себя инструменты, которые помогут вам писать сообщения о фиксации, создавать журнал изменений, создавать выпуски и многое другое. Многие вещи могут занять много времени. Они хорошо задокументированы, поэтому вам не нужно писать документацию о собственном соглашении о сообщениях коммитов.
Мы поговорим о двух из них Обычные коммиты (открывается в новом окне) и gitmoji (открывается в новом окне).
Обычные коммиты
Это спецификация, вдохновленная рекомендациями по сообщениям коммитов Angular. В нем есть несколько интересных правил, таких как:
- Перед фиксацией должен стоять тип (feat, fix)
- Может быть предоставлена область действия, чтобы указать на конкретный раздел кодовой базы (действительно интересно для монорепозитория).
- Критические изменения должны быть включены в раздел нижнего колонтитула.
Вот как сообщение фиксации должно быть структурировано с использованием этой спецификации:
[optional scope]: <description>[optional body][optional footer(s)]
Для получения дополнительной информации вы можете посмотреть их спецификации(opens new window)
гитмодзи
Я люблю смайлики, всем это нравится ❤, gitmoji лжет о категоризации коммитов с использованием смайликов. Я думаю, что это хорошо подходит для визуализации причины фиксации, поэтому я думаю, что это соглашение хорошо для всех.
Я был не совсем честен в своих предыдущих примерах коммитов из gitmoji-changelog. Как вы уже должны были догадаться, отсутствует часть.
:recycle: Make core independent from the git client (#171)
:whale: Upgrade Docker image version (#167)
:sparkles: Add maven preset (#172)
:sparkles: Add a generic preset using configuration file (#160)
:recycle: Improve error messages for preset system (#161)
:construction_worker: Publish Canary version on master push (#141)Эти текстовые псевдонимы широко используются в таких инструментах, как Slack, Discord и т. д. В большинстве инструментов менеджера репозитория, таких как GitHub или GitLab, AzureDevops интерпретирует их и хорошо отображает в пользовательском интерфейсе:
♻️ Make core independent from the git client (#171)
🐳 Upgrade Docker image version (#167)
✨ Add maven preset (#172)
✨ Add a generic preset using configuration file (#160)
♻️ Improve error messages for preset system (#161)
👷♂️ Publish Canary version on master push (#141)Мне нравится это соглашение, потому что я с первого взгляда знаю, какие изменения вносятся в коммит. Он поставляется с cli под названием gitmoji-cli (opens new window), который помогает вам писать ваши сообщения о коммитах, и я сделал для него генератор журнала изменений.
Их больше. Имейте в виду, что это рекомендации, вы можете комбинировать их, чтобы получить что-то, что удовлетворит ваши потребности.
Want to Connect? Say Hello on: LinkedIn, GitHub, and Blog.
