Создание и сопровождение Pull Request

При работе над проектом будут создаваться feature-ветки в git, которые потом необходимо вливать в основную ветку (продуктовую или develop, в зависимости от деталей workflow, который используется на проекте). Так или иначе, очень важно понимать, что просто создать Pull Request — это еще не завершение вашей задачи.

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

Как оформить Pull Request

Заголовок

Прежде всего ему нужно дать осмысленное название, которое коротко отразит вносимые вами изменения в проект: «добавлен вывод последних новостей», «исправлена ошибка открытия меню» и так далее. Но самое важное — Pull Request должен иметь определенные маркеры в заголовке, отражающие его текущее состояние. Обычно такими маркерами выступают [WIP] (Work In Progress) и [RFC] (Ready For Comment).

Эти маркеры нужны прежде всего для ревьюеров. Если ревьюер увидит Pull Request с маркером [RFC], то он сможет приступить к code review, когда у него будет на это время. Если же в заголовке вашего Pull Request будет стоять маркер [WIP], то будет сразу понятно, что этот Pull Request проверять еще рано.

Кроме того, эти маркеры могут меняться, например, Pull Request уже имел маркер [RFC], но в результате code review были выявлены некоторые проблемы, которые следует устранить. В этом случае необходимо изменить [RFC] на [WIP]. Такой подход поможет сэкономить время ревьюеров, так как они не будут заглядывать в Pull Requests, которые в данный момент не готовы к review.

В некоторых случаях в заголовок Pull Request следует добавлять еще и идентификатор issue, отделенный общепринятыми разделителями, например [issue-0001]. Это удобно, когда ваш Repository Hub (Bitbucket, Gitlab) умеет строить ссылки на issue по его идентификатору. В этом случае, следует придерживаться в проекте правила: название ветки должно быть равно идентификатору issue. Это позволит вам очень удобно находить как саму задачу, так и ее реализацию.

В итоге, название вашего Pull Request должно быть приблизительно таким:

[RFC] [issue-id] Добавлена возможность оформлять заказ одним кликом

или, если в вашем Repository Hub (Github) нет линков на issues, в названиях Pull Requests:

[WIP] Исправлена ошибка при клике по ссылке на новость

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

Тем не менее, иногда стоит дублировать текстовые маркеры в заголовке и лейблы github, например, если в вашем проекте есть интеграция github c trello, slack и так далее. Лейблы Github в этих сервисах видны не будут, а текстовые маркеры - будут.

Описание

Описание Pull Request должно быть максимально информативным. Не нужно писать в нем все, что сделано в вашей feature-ветке, обычно это и так описано в задаче, породившей вашу feature-ветку. В описании следует писать почему вы сделали так, как сделали. Можно еще добавить пару слов о том, на что ревьюерам стоит обратить особое внимание.

Помните, что описание Pull Request в идеале должно ответить на все возможные вопросы.

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

Сопровождение Pull Request

Как уже было описано выше, ваш Pull Request может потерять актуальность и следить за этим - ваша обязанность. Ревьюер, конечно, может заметить это раньше и сообщить вам, что ваш Pull Request с маркером [RFC] имеет на данный момент множество конфликтов с target-веткой. Но более корректно, если вы будете сами следить за актуальностью своего Pull Request.

Важно понимать, что чем раньше вы ответите на вопрос в вашем Pull Request или разрешите конфликт в коде, тем быстрее этот Pull Request вмержат в target-ветку.

Но бывают ситуации, когда конфликты появляются чаще, чем вы успеваете их разрешать. В этом случае, лучше всего поставить маркер [WIP] и дождаться стабилизации участка кода, который начал активно конфликтовать с вашим Pull Request. Такое бывает, когда происходит merge нескольких похожих Pull Requests.

Code review

Неотъемлемая часть жизненного цикла любого Pull Request - это code review. Любой из разработчиков в проекте может выступить ревьюером любого Pull Request. Очень важно понимать, на что стоит обращать внимание в Pull Requests, а на что - нет. Вы, как автор Pull Request или как ревьюер, в любом случае должны знать эти правила:

• Не стоит тратить время на review стилистических нюансов кода. Для этого существуют линтеры. Если в вашем проекте большую часть времени code review занимает обсуждение размера табуляции или точки с запятой в конце строки, то это уже не code review.
• Не стоит писать комментарий, если он не способствует существенному улучшению кода. Вполне возможно, что в Pull Request есть место в коде, которое на ваш вкус выглядит не очень хорошо. Если ваш комментарий не позволит улучшить читаемость/производительность/поддерживаемость этого участка кода, то не стоит тратить как свое время, так и время автора этого кода.
• Задавайте вопросы в местах, в которых сомневаетесь. Если у вас есть сомнение на счет определенных деталей реализации задачи, то обязательно задайте вопрос. Code review - это, кроме всего прочего, отличный способ распространять знания о проекте среди членов команды. Задать вопрос и получить ответ - отличный способ узнать о деталях реализации незнакомой вам части проекта.

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

В идеале, Pull Request должен автоматически проверяться линтерами, должны прогоняться автотесты, после чего уже ревьюеру следует тратить время на code review. К сожалению, такая автоматизация может быть не на всех проектах, поэтому автору Pull Request в такой ситуации перед проставлением маркера [RFC] в заголовок Pull Request нужно прогнать линтеры и автотесты, чтобы убедиться, что все в порядке.

Желательно, чтобы code review проводили несколько человек (как минимум двое), но не стоит назначать ревьюерами всю команду. Это не очень сильно увеличит эффективность code review, но значительно удорожит этот процесс. Но бывают и исключения, когда все члены команды должны принять участие в code review. Обычно это связано с радикальными изменениями в проекте, либо в его инфраструктуре.

В итоге

После того, как вы создали Pull Request, успешно прошли стадию code review, исправили все замечания и ответили на все вопросы, ваш Pull Request наверняка получит approve от всех ревьюеров, а уже после этого последует его merge в target-ветку. Поздравляю! Работа над этой задачей завершена, если конечно она не вернется к вам после тестирования QA-инженерами.