Манифест контрольного списка

Важность шаблонов мерж-реквестов

Заполнение контрольного списка часто считается рутинной задачей. Но что, если бы я сказал вам, что контрольные списки действительно необходимы для правильного выполнения работы?

Было доказано, что контрольные списки помогают уменьшить количество человеческих ошибок при выполнении сложных задач, таких как полет на самолетах или выполнение хирургических операций (см. Манифест контрольного списка от Атула Гаванде).

Так почему бы не применить контрольные списки к разработке программного обеспечения? В этой статье мы рассмотрим преимущества использования шаблонов запросов на слияние (или запросов на вытягивание) перед слиянием нового кода.

Шаблоны мерж-реквестов

Большинство компаний-разработчиков программного обеспечения используют Git вместе с такими платформами, как GitHub или GitLab, чтобы обеспечить контроль версий своего кода.

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

И GitHub, и GitLab позволяют настроить репозиторий для включения шаблона запроса на слияние, который в основном представляет собой форму, которую разработчик заполняет при создании запроса на слияние.

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

Шаблон мерж-реквеста может выглядеть так:

Description: what are you changing and why
Ticket Info: links to tickets in your task management system like JIRA or Workfront
Test Plan: step-by-step instructions for how someone could verify that your code works
QA Risk: low, medium, or high
Screenshots or Videos: proof of your code working properly
Additional Checklist Items:
[ ] I have written automated tests for this change
[ ] I have updated documentation as needed
[ ] The code works in all supported browsers

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

Описание

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

И не хотите ли вы знать, почему инженер решил проблему так, как они это сделали, или какие альтернативы они рассмотрели? Я мог бы.

Описание мерж-реквеста помогает предоставить контекст для проверки кода.

Информация о билетах

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

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

План тестирования

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

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

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

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

Риск обеспечения качества

Риск обеспечения качества - это, по сути, субъективная мера того, насколько велико это изменение. Что может случиться, если что-то пойдет не так? Будет ли у ввода текста неправильный цвет рамки? Или ваш вход в систему или процесс оформления заказа прервутся? Понимание потенциального воздействия изменения кода может помочь рецензентам быть более тщательными в своих обзорах.

Скриншоты или видео

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

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

Дополнительные элементы контрольного списка

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

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

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

Критика

Теперь о недостатках. Может ли инженер просто проигнорировать шаблон мерж-реквеста и не заполнять его? да.

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

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

Заключение

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