Добавьте структуру и улучшите читаемость ваших коммитов

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

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

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

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

feat: add an endpoint to get contents recommendation
GET /contents/:topics/recommendation returns a JSON with some
recommendations for the user.

Ниже приводится более длинное сообщение о фиксации с более подробной информацией. Он имеет область видимости (api) и нижний колонтитул с метаданными.

test(api): assess test suite quality with mutation analysis
Add a new executable `mutation-analysis` that analyses the API's
test suite and returns a score that we can use to keep track of
how good our tests are at catching defects. This is a better
approach than code coverage.
It works by running the tests against mutants of the API
(slightly different versions of the code, e.g. a < could be
replaced with a <=) and counting the proportion of mutants that
the tests catch. This is relying on the assumption that most
mutants are invalid and should make the tests fail.
Issue: ABC-456
Approved-By: Tom Feron

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

Легкий

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

Таким образом, стоимость запуска с обычных коммитов практически равна нулю.

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

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

Проще пройти

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

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

Что я заметил после того, как какое-то время использовал обычные коммиты, так это то, как они подталкивают меня к тому, чтобы давать больше объяснений и контекста. Если бы я раньше писал сообщения о фиксации, такие как «Исправить тесты» - давай, а кто этого не сделал? - Теперь я бы написал такие сообщения о фиксации:

test(api): fix comment's JSON in endpoint test
The key `actorId` was deprecated a few months ago and removed
recently but the test suite hadn't been updated.

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

1 фиксация = 1 изменение

Еще кое-что, что я заметил при использовании обычных коммитов, - это то, как они заставляют меня фиксировать одно изменение за раз. Когда вам нужно начать коммит с feat(task-runner): something, вы дважды подумайте, прежде чем одновременно совершать какой-то несвязанный рефакторинг.

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

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

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

Отслеживание выпуска

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

Еще одна ситуация, когда отслеживание релизов полезно, - это анализ трафика. Знание о том, что всплеск конверсии вашего веб-сайта произошел сразу после развертывания 3d0e862dacf9655236bd73c31676170037e87483 или даже fix spacing, не совсем полезно.

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

Журнал изменений

При подготовке к обзору спринта вас когда-нибудь спрашивали (или спрашивали сами коллеги): «Что мы отправили на этой неделе?» Ваш диспетчер задач или доска канбан могут не очень помочь в отображении того, что на самом деле было объединено. Некоторые изменения не фиксируются такими инструментами, а другие являются лишь частью проблемы Jira, но все же приносят пользу и заслуживают упоминания.

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

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

Заключение

Учитывая, насколько легко начать использовать обычные коммиты и практически не требуются затраты, вы бы посоветовали любому хотя бы попробовать и сами посмотреть, как все закончится.

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

Если вам нравятся истории, подобные этой, подумайте о членстве в Medium и / или подписке.