Разница между хорошей и плохой фиксацией может быть огромной. Неинтересно спрашивать своего коллегу — или себя в прошлом — о том, что было за конкретное изменение или каково текущее положение вещей. Если вы правильно внесете изменения в свою кодовую базу, вы сможете избежать головной боли в будущем.
Эта статья призвана предоставить подробное руководство по лучшим практикам коммитов программного обеспечения.
Зачем беспокоиться?
Если вы уже храните свои проекты на GitHub, вы можете предположить, что файлы в безопасности, и что всякий раз, когда вам нужно обновить код, вы будете извлекать изменения, и этого достаточно. Все это могло быть правдой. Но давайте посмотрим, каких потенциальных проблем вы можете избежать, приложив дополнительные усилия, и какие дополнительные преимущества ожидают, если вы это сделаете.
Ни один человек — не остров, ни в команде, ни по отдельности
Приведенное выше рассуждение обычно исходит от разработчика, привыкшего работать в одиночку. Но в тот момент, когда им нужно поделиться кодом с кем-то еще, мы можем ожидать, что все станет беспорядочно и потребует много объяснений. Типа, много.
Помните, что наша работа не заканчивается простым написанием кода. Нам также необходимо управлять вещами, а для этого требуется определенная степень организации и методологии. И хотя работа в команде легче выявляет проблемы, вызванные плохой организацией, мы также можем извлечь выгоду из лучшего подхода при работе в одиночку.
Atomic и Bloated Commits
Нам всем нужно было отменить небольшое изменение, и мы начали искать его, когда массивная фиксация изменяет десятки файлов и добавляет несколько функций. Насколько проще был бы откат, если бы он находился в одной фиксации, которая решала только эту конкретную проблему?
The Messy, Bloated Way
git add * git commit -m "new components"
В этом примере мы можем поспорить, что затронуто большое количество файлов. Кроме того, сообщение «новые компоненты» ничего не говорит нам — например, о том, какие компоненты, какие функции для этих компонентов, а также является ли эта функция новой или проводится рефакторинг. Кроме того, исправляются ли какие-либо существующие ошибки?
Эта информация будет важна, когда нам понадобится что-то изменить или восстановить. Мы будем пытаться найти иголку в стоге сена и, возможно, в конечном итоге просто взглянем на кодовую базу и потратим драгоценное время на отладку, пока мы на ней.
The Atomic Way
git add ui/login.html static/js/front-end.js git commit -m "validate input fields for login"
Теперь мы к чему-то приближаемся, поскольку начинаем иметь более четкое представление о том, что происходит с этим единственным коммитом.
Хитрость в том, что мы можем полуавтоматически фиксировать изменения как часть нашего рабочего процесса. То есть выполнение блока работы, которая выполняет что-то очень конкретное (реализация определенных функций, исправление ошибки, оптимизация алгоритма), тестирование (и написание модульного теста, если необходимо), добавление описания, пока наши воспоминания свежи, и совершая сразу. Промыть и повторить.
Структура хорошей фиксации
Эти правила не высечены в камне, но могут помочь вам оценить, как может выглядеть хороший коммит:
- недвусмысленно: никаких сомнений в том, что делают эти изменения коммита.
- информативный: четкое описание того, что делает код, даже предоставление ссылок или дополнительной информации, когда это необходимо, и отметка ошибок или проблем, которые решаются.
- атомарный: решение одной задачи за раз (подумайте о «блоке работы», который может быть от 20 минут до 2 часов или даже 2 минут, если это было быстрое исправление ошибки).
Давайте посмотрим на шаблон и разберем его:
<type/component/subsystem>: <subject> <BLANK LINE> <body>
Type, Components, or Subsystem
Это будет набор функциональных возможностей программного проекта, которые можно сгруппировать вместе. Например, то, что AngularJS называет типами, или то, что SrummVM называет подсистемами.
Примеры
В своих проектах я часто использую термин «компонент», например:
- i18n, l18n
- authentication
- other, 3rd party
- QA, tests
- tools
- UI, GUI
The (Mandatory) Subject
Тема — простая и понятная строка, описывающая, что делает коммит, чтобы каждый мог получить твердое представление с первого взгляда.
Когда дело доходит до форматирования темы, я часто следую этим простым рекомендациям:
используйте императив («изменить» вместо «изменено»)
не делайте первую букву заглавной
нет точки (.) в конце
добавьте «(…)», если доступно дополнительное тело
Примеры
Это могут быть допустимые предметы:
- i18n: поддержка упрощенного китайского (zh-hans)
- auth: рефакторинг входа в Google
- другое: добавить jQuery 3.4.1
- QA: пройти тест развертывания AWS (…)
Как видите, нет никаких догадок относительно того, что делают эти коммиты, и в последнем коммите QA мы также видим, что доступна дополнительная информация (возможно, ссылки на соответствующую документацию или дальнейшее объяснение исправления).
The (Optional) Body
Иногда нам нужно предоставить больше деталей, чем умещается в строке темы, чтобы обеспечить контекст, например, при исправлении постоянной ошибки или при взломе алгоритма.
В этих случаях вы можете просто ввести строку с двойным разрывом (чтобы тема работала как заголовок) и ввести столько информации, сколько необходимо.
Пример
Для нашего предыдущего коммита QA мы могли бы сделать что-то вроде этого:
QA: pass AWS deployment test (...) I added a `DJANGO_SETTINGS_LIVE` environment variable to [AWS Elastic Beanstalk](https://aws.amazon.com/elasticbeanstalk/)'s `django.config` file, so that the synchronization management commands in `db-migrate` are _only_ executed in production.
Как видите, за телом может быть труднее следить, и это нормально, поскольку оно предназначено для тех, кто активно ищет больше деталей. Любой может получить представление о том, что делает коммит, просто прочитав тему, а тело будет служить для дальнейшего контекста, сохраняя нам постоянные электронные письма или обмены в Slack!
— “Hey, how did you get to …”
— “Read the commit 😑.”
Не забывайте решать проблемы
Наконец, есть проблема решения проблем (каламбур!). Любой достойный средний и крупный проект разработки программного обеспечения должен использовать средство отслеживания проблем как способ отслеживать задачи, улучшения и ошибки — будь то Atlassian Jira, Bugzilla, средство отслеживания проблем GitHub или другое.
Issues Management
Если вы не знали, в большинстве систем вы можете управлять проблемами прямо из сообщения о фиксации!
Вы можете:
- закрыть / решить проблему
- повторно открыть проблему, если она была закрыта ранее
- держать вопрос, следует особенность отложить на потом
Все, что нужно, — это использовать эти ключевые слова с идентификационным номером проблемы.
Примеры
- инструменты: консолидировать данные БД с помощью cron job; решение № 46
- UI: добавить процедуру сериализации пользовательского ввода; обнаружена ошибка, открыто # 32
- auth: закомментировать вход в Facebook; удерживать # 12
Кроме того, вы все равно можете ссылаться на проблему как на способ предоставления контекста, даже если вы не хотите изменять ее статус — например, «см. № 12».
Все эти ссылки будут видны любому, кто откроет эту проблему в трекере, что позволяет легко следить за ходом выполнения данной задачи или ошибки.
Завершение
Вы не всегда будете делать это правильно (я, например, не понимаю!). Все будет запутываться, и время от времени вы не будете следовать правилам, которые вы установили для себя или своей команды — а это часть процесса. Но, надеюсь, вы знаете, что можете быть очень организованными с помощью всего лишь нескольких обновлений рабочего процесса, экономя время для себя и своей команды в долгосрочной перспективе.
Я также установил на собственном опыте, что не имеет большого значения, задействованы ли в проекте десять разработчиков или он полностью выполняется вами. Проще говоря, правильно фиксируйте изменения в своей кодовой базе — это важная часть хорошего управления проектами.
