Как улучшить свой пул-реквест

0
846
views

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

Но если это не вопрос жизни и смерти, то перед тем, как нажать кнопку слияния, вам придется преодолеть серьезное препятствие — получить одобрение своего пул-реквеста (pull request). Давайте поговорим о том, как сделать PR максимально эффективным, чтобы ваши рецензенты точно знали, на что они смотрят, а вы могли побыстрее нажать кнопку слияния.

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

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

Изложение вашего пул-реквеста

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

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

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

От редакции Techrocks: возможно, вас также заинтересует статья «Как написать хороший issue».

Организация пул-реквеста

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

Но что делать, если вам нужно внести исправление или сделать рефакторинг, а вы уже сделали коммиты? Это совершенно нормально! Как разработчики, мы можем изменить историю с помощью ребейсинга (от англ. rebase).

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

От редакции Techrocks: подробнее читайте в статье «Простое объяснение Git Rebase».

Обращайте внимание на размер вашего PR

Если наши коммиты — это главы нашего пул-реквеста, то наши фактические реализации и изменения кода — это сама история. Важно, чтобы мы обращали внимание на размер нашей истории. Существует принцип программирования, называемый принципом единой ответственности (Single-Responsibility Principle). Он гласит:

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

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

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

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

Вступление к пул-реквесту

Мы рассказали о главах нашей PR-истории и о самой истории, но какая же хорошая история без вступления? Вот тут-то и приходят на помощь заголовок и описание.

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

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

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

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

И наконец, «Как». Как ваши рецензенты должны тестировать ваш код? Пройдитесь по шагам, чтобы воспроизвести свои изменения в демонстрационной среде. Все должно быть максимально наглядным и четким. Укажите прямые ссылки на маршрут, который необходимо протестировать, и все флаги функций или разрешения, которые могут потребоваться. Также необходимо указать точные сценарии, которые необходимо протестировать. Например, список действий для воспроизведения состояния ошибки.

Станьте собственным рецензентом

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

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

Продолжение разговора

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

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

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

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

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

Перевод статьи «A Guide to Perfecting Pull Requests».

ОСТАВЬТЕ ОТВЕТ

Please enter your comment!
Please enter your name here