Правильно вносите изменения в свою кодовую базу

Что такое схемы базы данных Изучение

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

Эта статья призвана предоставить подробное руководство по лучшим практикам коммитов программного обеспечения.

Зачем беспокоиться?

Если вы уже храните свои проекты на 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

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

Когда дело доходит до форматирования темы, я часто следую этим простым рекомендациям:

используйте императив («изменить» вместо «изменено»)
не делайте первую букву заглавной
нет точки (.) в конце
добавьте «(…)», если доступно дополнительное тело

Примеры

Это могут быть допустимые предметы:

  1. i18n: поддержка упрощенного китайского (zh-hans)
  2. auth: рефакторинг входа в Google
  3. другое: добавить jQuery 3.4.1
  4. QA: пройти тест развертывания AWS (…)

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

The (Optional) Body

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

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

Читайте также:  MATLAB - Типы данных

Пример

Для нашего предыдущего коммита 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».

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

Завершение

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

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

Оцените статью
bestprogrammer.ru
Добавить комментарий