Привет, Хабр! Мы в beeline cloud не только создаем современные цифровые продукты, но и обучаем разработке в облаке студентов нашего курса Base Cloud DevOps. Однако выстроить эффективный процесс невозможно без знания основных инструментов. Один из них — система контроля версий Git. Перевели для вас статью, которая поможет извлечь из работы с этой утилитой еще больше пользы. Когда-то я и не задумывался о существовании каких-то правил для составления комментариев к коммитам, но потом любознательность взяла верх. Мне казалось, что простых сообщений наподобие «добавлена функция 2», «исправлена ошибка на панели навигации» или просто «foo» вполне достаточно. Однако моя уверенность в том, что комментарии к коммитам, как правило, никто не читает, оказалась ошибкой. Хорошо составленные commit messages очень важны, они помогают нам самим в будущем извлечь максимальную пользу из своих стараний и продуманности. Коммиты выполняют роль своеобразных кирпичиков в ремесле программиста. При правильном оформлении они и вовсе превращаются в «глазурь» на тортике из вашего кода и приносят значительную пользу. Хорошо написанные комментарии обеспечивают вам правильный контекст. Хорошие коммиты свидетельствуют об умении человека работать в команде — Питер Хаттерер, Linux. Распространенная в среде разработчиков ошибка – отношение к Git-репозиторию как к обычному хранилищу резервных копий. Беспорядочные коммиты, фиксирующие текущее состояние кода, могут затруднить восприятие хронологии изменений при последующем изучении кодовой базы. Коммиты типа «WIP», «Ушел на обед», «Хватит на сегодня», «Устал как лошадь», «Всем хороших выходных» и «Я первый»" только засоряют ваш Git-лог, затрудняя понимание существенных правок, поскольку ни одно из этих сообщений не представляет никакой дополнительной ценности. Раздельная фиксация изменений для разных файлов может привести к проблемам при просмотре истории коммитов или взаимодействии с другими членами команды. Сложно понять весь контекст изменений и их связь друг с другом. Например, я работаю над интернет-магазином. Вот чего мне ❌ не следует делать: Таким образом логи очень скоро превратятся в кучу хлама. Коммиты должны быть четкими, лаконичными, организованными в логические блоки. Например, после завершения верстки макета и проработки шапки и футера будет правильнее объединить изменения перед коммитом: Я понимаю, в теории это выглядит проще, чем будет на деле. Именно поэтому стоит вести приватную ветку специально для фиксации небольших изменений, прежде чем консолидировать их в main посредством объединения. Создание коммита не обязательно означает, что он должен постоянно находиться в бескрайних просторах вашего git-лога. Воспринимайте приватные ветки как персональный скетчпад программиста, где можно свободно экспериментировать, не опасаясь, что кто-то будет пристально следить за вашей работой. Представьте себе такой сценарий: вы работаете над кодом, и вам нужно отлучиться на небольшой перерыв, или, возможно, вы собираетесь поужинать. Страх потерять текущий прогресс побуждает вас закоммитить изменения — это идеальный пример использования приватной ветки. Неважно, заканчиваете ли вы работу на сегодня или просто хотите сделать спонтанный коммит, эти изменения окажутся в вашей частной ветке. В условиях совместной работы важно, чтобы именование приватной ветки было очевидным. Ведь нельзя же допустить, чтобы такие коммиты появлялись в публичном поле. Неважно, как — путем корректного именования или договорившись с коллегами напрямую, сделайте очевидным тот факт, что содержимое этой ветки не предназначено для их глаз. Вот хороший пример названия для приватной ветки: private/do-not-use-this. Каждый коммит, который становится частью вашей публичной ветки, должен представлять собой хорошо продуманную, самодостаточную, обратимую и четко описанную единицу работы. Давайте взглянем на проект интернет-магазина, который мы начали «разрабатывать» выше. Здесь мы выступаем в качестве фронтенд-разработчика, отвечающего за добавление в магазин функции корзины. Далее ваша работа будет строиться так: Вы начали с улучшения CSS для раздела корзины и выполнили соответствующий коммит. По мере продвижения вы внедрили в корзину код на JavaScript, и это привело к еще одному коммиту. В стремлении к совершенству вы заметили проблему с центровкой текста и уделили время доработке CSS, после чего выполнили еще один коммит. В ходе дальнейшей разработки была выявлена и устранена ошибка, связанная с поведением счетчика при добавлении товаров в корзину. Этот мелкий фикс также был закоммичен. Напоследок вы решили улучшить пользовательский опыт, добавив анимацию загрузки при нажатии на кнопку оформления заказа, и выполнили финальный коммит. Давайте-ка взглянем на логи: Если все эти изменения включить в основную ветку фич наряду с другими фиксами, то процесс рецензирования здорово осложнится. Начните со смены рабочей ветки: Затем объедините все коммиты из вашей ветки private/do-not-use-this в feature/cart-section с помощью единого коммита: После слияния необходимо составить ясный и содержательный комментарий: Приведенные здесь правила содержат рекомендации и лучшие практики для обеспечения правильного форматирования комментариев и донесения информации в понятном виде. Разные правила могут содержать разночтения в части написания текста/темы коммита, однако их конечная цель состоит в улучшении читабельности и понятности комментариев к коммитам в системе контроля версий Git. При формировании темы коммита рекомендуется придерживаться краткости и фокусировки на главном. Строка темы служит кратким изложением цели коммита и в идеале не должна превышать 50 символов. Если вы не можете уложиться в 50-символьный лимит, это может свидетельствовать о том, что цель коммита не сформулирована. Между тем, коммиты должны быть ясными, краткими и самодостаточными. Придерживаясь этого правила, вы вынуждены будете выделять лишь наиболее важную информацию, что позволит вашей команде и вам самим с первого взгляда понять суть изменений. При составлении комментария оставьте только одну заглавную букву — с нее должна начинаться тема. Остальную часть сообщения, включая все дополнительные сведения, оставьте в нижнем регистре. Причина, по которой в строке темы не ставится точка, отчасти имеет исторические корни, а отчасти заключается в сохранении единого стиля. Принято рассматривать строку темы как заголовок или команду, поэтому она пишется в повелительном наклонении (например, «Добавить функцию или «Исправить ошибку», а не «Добавлена функция» или «Исправлена ошибка»). Отсутствие точки в конце помогает соблюсти это правило и сохранить лаконичность. Это правило может показаться странным, но оно основано на практической целесообразности. Многие разработчики используют для работы с Git интерфейсы командной строки, в которых часто отсутствует автоматическое форматирование. Поэтому для обеспечения единообразия и разборчивости комментариев были введены специальные правила оформления коммитов. Важно пояснить, что важность соблюдение этого правила обусловлена тем, что пользователи командной строки могут столкнуться с усечением текста в строке длиннее 72 символов. В большинстве случаев длина ваших комментариев будет превышать 72 символа. В таких случаях рекомендуется разрывать текст и писать продолжение на следующей строке, как показано в приведенном ниже комментарии: В заключение отмечу, что стандартной практикой обозначения маркированных пунктов списков является использование дефиса или звездочки с пробелом. Очень полезно составлять комментарии с оглядкой на то, что при выполнении коммита будет выполнено определенное действие. Постройте комментарий таким образом, чтобы он логически завершал предложение «Применение коммита позволит...».  Например, вместо git commit -m "Исправлены баги в верстке" ❌, используйте следующее git commit -m "Исправить баги в верстке" ✔. То есть, если применить этот коммит, он действительно позволит исправить ошибку на странице макета. Если ограничить смысловую нагрузку комментария вопросами «что сделано?» и «почему сделано?», получится краткое, но информативное объяснение каждого изменения. Разработчики, которым интересно, как был реализован код, могут обратиться непосредственно к кодовой базе. Поэтому подчеркните, что именно было изменено и каковы причины этого изменения. И не забудьте упомянуть, какой компонент или участок кода были затронуты. Angular является ярким примером эффективного применения комментариев. Команда разработки придерживается специальных префиксов, таких как "chore: , "docs: ," "style: ," "feat: ," "fix: , "refactor: ," и "test: ." Благодаря включению этих префиксов в тему коммита, беглого взгляда на историю достаточно, чтобы понять, какие изменения производились в коде. Не забывайте, что главным приоритетом является обеспечение прозрачности и осмысленности каждого коммита. Хорошо составленный комментарий выполняет роль исторического документа, объясняющего «что, «почему», но не «как» было сделано в проекте. Помните, что история коммитов — это средство организации эффективной совместной работы. Возьмите за правило создавать информативные, краткие и последовательные комментарии. Хотите углубить свое понимание Git'а? Ознакомьтесь с этими ресурсами: https://git-scm.com/doc https://git-scm.com/book/en/v2 https://lab.github.com/ https://www.atlassian.com/git/tutorials https://learngitbranching.js.org/ https://www.gitkraken.com/git-cheat-sheet https://www.git-tower.com/learn/ beeline cloud — secure cloud provider. Разрабатываем облачные решения, чтобы вы предоставляли клиентам лучшие сервисы.