Не знаю, как вам, а мне нравится ощущение, которое возникает, когда я нажимаю кнопку слияния (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».
Запись Как улучшить свой пул-реквест впервые появилась Techrocks.