Сообщения ваших коммитов могут рассказывать историю или быть мусором. Это твой выбор

Сообщение фиксации - это просто сообщение, которое вы добавляете перед постановкой изменений кода и которое вы можете увидеть в истории своего репозитория git; звучит очень просто, но тогда почему все так сильно к ним относятся?

Насколько я могу судить, есть два типа сообщений о фиксации: информативные и хорошо написанные, и сообщения типа «некоторые изменения здесь…».

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

Но почему?

О важности четких и информативных сообщений о коммитах

Прежде чем перейти к тому, как писать хорошие сообщения о коммитах и ​​даже поделиться с вами своим методом сообщений о коммитах, позвольте мне объяснить, почему так важно иметь четкие описания коммитов в истории вашего проекта.

Я сосредоточусь на объяснении важности сообщений коммитов с разных точек зрения:

Рецензент кода

Я проработал несколько лет техническим руководителем, и часть моей работы заключалась в выполнении проверки кода несколькими удаленными командами, которые находились на расстоянии более 10 000 км и с разницей в 10 часов. Иногда я приходил в офис, чтобы найти довольно длинный PR, работу нескольких разработчиков в течение нескольких дней, с затронутыми сотнями строк кода, где каждый коммит говорил что-то вроде «исправления», «дополнительные исправления» , «Здесь изменяется» или «совершает».

Помимо очевидного фактора - который я не собираюсь вдаваться в подробности - почему PR были такими большими - когда я пытаюсь поработать над ними, у меня возникает много-много вопросов, которые я не мог сразу задать, поскольку команда была уже спит дома (из-за разницы во времени). Поэтому я сидел и пытался понять, что происходило, и пытался выяснить из их истории коммитов, как развивались изменения, чтобы получить более ясную картину того, что происходило.

С коммитами, подобными тем, о которых я упоминал ранее, это было невозможно. У меня не было шансов. Я проверял код как можно лучше и оставлял комментарии, которые команда могла бы забрать на следующий день и дать разъяснения. Это было неэффективно.

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

Новый столяр

Из-за характера организации команды у нас была высокая ротация среди членов удаленной команды; опять же, я не буду вдаваться в подробности того, почему нам просто пришлось смириться с этим. Наша кодовая база была довольно большой для размера команды и пугала новичков, особенно тех, у кого был меньший опыт работы в качестве разработчиков. У нас всегда был кто-то, кто помогал им интегрироваться в команду, кто-то из своего часового пояса, но это была непростая задача.

Наличие доступа к истории git может помочь любому разработчику понять, как развивалась конкретная страница, служба, файл или метод, или может помочь понять, почему что-то было добавлено или когда что-то было удалено. Но перемещаться по миру «исправлений», «немного текста здесь» и «никаких сообщений» может быть очень сложно.

Может показаться, что это не так уж много, но для всех, кто, как я, открывают git-историю проекта, когда впервые начинают над ним работать, это очень помогает!

Разработчик

Да, хорошие сообщения о фиксации могут помочь даже вам! Иногда мы сталкиваемся с такими вопросами, как почему этой кнопки больше нет или когда этот элемент был удален или добавлен? И мы часто ищем истории пользователей, в которых говорится об этом. Но это не всегда есть, иногда мы что-то удаляли случайно или добавляли что-то, что сложно найти в таких инструментах, как Jira или Azure DevOps. Однако это может быть очень легко увидеть в коде и истории коммитов. Так что сэкономьте себе время и создавайте потрясающие коммиты!

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

3 различных рабочих процесса для сообщений о фиксации

В командах, над которыми я работал на протяжении многих лет, я нашел три подхода к работе с сообщениями коммитов, и, что достаточно интересно, они могут быть этапами, с которых вы можете переводить свою команду из одной категории в другую, пока ваша история кода не будет похожа на роман Эдгара Аллена По. .

Какая разница?

Первый шаг - это команды, которым все равно или они не осознают важность сообщений коммитов, и они просто кладут туда все, что хотят.

Зафиксируйте то, что хотите; мы сжимаем коммиты при слиянии

Некоторые команды понимают важность сообщений фиксации. Тем не менее, разработчики не хотят беспокоиться о написании хороших сообщений о фиксации, поэтому они фиксируют все, что захотят, но при этом предоставляют описательный комментарий к PR. Эти команды обычно скручивают коммиты, так что, когда вы видите историю, вы видите только четкие сообщения, написанные в PR. Преимущество в том, что у вас есть чистая история коммитов; недостатком является то, что любая фиксация, произошедшая в функциональной ветке, исчезла.

Это неплохой подход, и он мне очень нравится, он определенно лучше, чем первый этап, однако тот, кто просматривает PR, не получит добавленной стоимости в виде четкого сообщения о фиксации, а ценная информация может быть упущена из истории проекта.

Каждое сообщение фиксации имеет значение

На этом этапе каждый разработчик в вашей команде пишет четкие и информативные сообщения о фиксации, которые могут быть полезны в процессе проверки кода, и вам не нужно отказываться от фиксации, и вы можете получить доступ к полной истории проекта.

Однако это может быть немного опасно, поскольку ваша история может значительно увеличиваться в зависимости от того, как часто разработчики совершают изменения.

Моя формула отличных сообщений о приверженности

Формат сообщения фиксации

Каждое сообщение фиксации состоит из заголовка, тела и нижнего колонтитула. Заголовок имеет специальный формат, который включает тип, область и тему:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

заголовок является обязательным, а область заголовка - необязательной.

Возвращаться

Если фиксация отменяет предыдущую фиксацию, она должна начинаться с «revert:», за которым следует заголовок отмененной фиксации. В теле должно быть написано: «Он отменяет фиксацию», где хеш - это SHA отмененной фиксации.

Тип

Должен быть один из следующих:

  • build: изменения, влияющие на систему сборки или внешние зависимости (примеры областей: gulp, broccoli, npm)
  • ci: изменения в наших файлах конфигурации и скриптах CI (примеры областей: Circle, BrowserStack, SauceLabs)
  • docs: Изменения только в документации
  • feat: Новая функция
  • fix: Исправление ошибки
  • perf: изменение кода, улучшающее производительность.
  • рефакторинг: изменение кода, которое не исправляет ошибку и не добавляет функции.
  • style: изменения, не влияющие на смысл кода (пробелы, форматирование, отсутствие точек с запятой и т. д.)
  • test: добавление недостающих тестов или исправление существующих тестов.

Сфера

Областью должно быть имя затронутого пакета npm или имя модуля или компонента.

Тема

Тема содержит краткое описание изменения:

  • используйте повелительное наклонение в настоящем времени: «изменить», а не «изменить» или «изменить»
  • не пиши первую букву с заглавной буквы
  • нет точки (.) в конце

Тело

Как и в случае подлежащего, используйте повелительное наклонение в настоящем времени: «изменить», а не «изменилось» или «изменилось». Тело должно включать мотивацию к изменению и противопоставлять это предыдущему поведению.

Нижний колонтитул

Нижний колонтитул должен содержать любую информацию о критических изменениях, а также место для ссылки на проблемы, которые фиксируются с помощью закрытий или ссылок.

Критические изменения должны начинаться со слова BREAKING CHANGE: с пробелом или двумя символами новой строки.

Пример

feat(Subscriptions): Support permission-based subscriptions
Update the audience object to support permission-based
References: #XXXXXX

Заключение

Истории Git - невероятно ценный инструмент. Однако иногда непонятно, что отличает «хорошее» сообщение фиксации от «плохого». Кроме того, решение, которое я предлагаю, может быть не лучшим для вашей команды. Это решение, которое я предлагаю и пытаюсь реализовать везде, где бы я ни находился, и пока еще ничего нет. Быть гибким; Важным моментом является то, что ясная история имеет значение, каким бы способом вы это ни реализовали.

Спасибо за прочтение!