Ревю пул реквестов что это

Что такое pull request?

@Pavel Mayorov, на официальном сайте GitHub — который, на мой взгляд, является наиболее авторитетным источником насчёт именования термина, — термин «pull request» пишется строчными буквами, примеры: About pull requests, Merging a pull request, Reverting a pull request. Спасибо.

4 янв 2017 в 8:49

@СашаЧерных он там по-разному пишется. Перейдите по той ссылке, которую вы приводили первый раз и посмотрите в самый низ

4 янв 2017 в 8:53

4 ответа 4

Сортировка: Сброс на вариант по умолчанию

Смотрим за руками.

1. Крутой программер создал репозиторий.
2. Вы сделали форк его репозитория (т.е. скопировали к себе).
3. Вы сделали какие-то крутые изменения в своём репозитории.

Теперь если вы хотите, чтобы крутой дядя внёс ваши крутые изменения в свой крутой код. И вы просите, чтобы он взял ваши изменения, т.е. сделал git pull . Это и называется pull request

Отслеживать
28.5k 12 12 золотых знаков 58 58 серебряных знаков 118 118 бронзовых знаков
ответ дан 10 авг 2012 в 13:18
Dmitry Manannikov Dmitry Manannikov
1,675 1 1 золотой знак 9 9 серебряных знаков 9 9 бронзовых знаков
А как теперь этот пулл реквест применить к своему репозиторию?))
11 авг 2012 в 9:26
Нажать «Accept Pull Request», не?
11 авг 2012 в 9:43

Что значит применить? Вы просите кого то (нажав кнопку на гитхабе) влить ВАШИ изменения в ЕГО репозиторий. Влить или не вливать — его дело.

11 авг 2012 в 9:43

Почему «крутой», «крутые»? Я мелочи, в основном, делаю. Исправляю небольшие баги, изменяю формат даты, добавляю улучшения в юзабилити и т. д. Самое смешное: пофиксишь опечатку — GitHub тебя уже в контрибуторы зачисляет. Спасибо.

28 сен 2016 в 3:31
git pull тут ни при чём. При принятии реквеста git merge делается.
12 дек 2016 в 7:57

К вышесказанному можно добавить следующее. Далеко не все пулл-реквесты принимаются разработчиками. Тут нужно соблюсти ряд правил:

1. Пулл-реквест (ПР) должен быть хорошо оформлен и содержать исчерпывающее описание.
2. Обычное правило, один баг — один ПР, одна фича — один ПР. Не нужно пытаться впихнуть сразу кучу всего.
3. Очень важно соблюдать Code Style того проекта, для которого вы делаете ПР. Пусть даже он кажется вам противоестественным (например вы всегда делаете отступы в виде 4 пробелов, а в проекте табы).

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

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

Отслеживать
ответ дан 17 сен 2015 в 18:50
3,324 1 1 золотой знак 15 15 серебряных знаков 32 32 бронзовых знака

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

еще добавки к вышесказанному: возможный (я им пользуюсь) механизм работы с репами/pr:

git clone https://github.com/ваш_юзернейм/sqlpp11.git

git remote add upstream https://github.com/rbock/sqlpp11.git (т.е. мы добавляем псевдоним upstream для оригинального репозитория, мы не можем добавлять в него изменения, но можем их получать)

git checkout -b названиеБранча (ветки)

теперь вы правите файлы в вашем origin, в вашей ветке, пушите их в свой форк гитхаба (origin), откуда и делаете pull-request

при этом вы можете сделать git merge/pull/fetch upstream с оригинального репозитория (upstream)

если в upstream настроена интеграция типа travis-ci (как в моем примере), лучше не делать пулл-реквесты, пока не настроите travis-ci для своего репозитория и ваши билды не будут работать правильно (чтобы не мучать мэйнтейнера upstream бессмысленными сообщениями о неудачных сборках в пулл-реквесте)

общий алгоритм работы примерно такой: git fetch; git merge upstream/ветка; (master/debug/и т.д.) сделали изменения: git push , изменения улетают в ваш форк на гитахабе. Eсли настроен travis, проходят тесты/сборки, когда вы уверены в качестве коммита, делаете pull request из вашего форка. Если PR приняли, делаете, допустим, git checkout master; git fetch; git merge upstream/ветка , чтобы ваш форк оставался консистентным с оригиналом.

вмердженные в upstream (оригиальный репозиторй) и в ваш origin/master (ваш форк на гитхабе, в данном случае) ветки можно удалять — руками или с помощью, например, https://github.com/arc90/git-sweep

Отслеживать
ответ дан 17 июн 2016 в 21:12
strangeqargo strangeqargo
5,754 20 20 серебряных знаков 32 32 бронзовых знака

1. Что такое pull request?

1. Определение

pull request — предложение изменения кода в чужом репозитории.

Вы делаете форк чужого репозитория (который иногда и сам может быть форком) → производите изменения в своём форке → посредством pull request предлагаете изменения владельцам репозитория, чей форк Вы сделали. На GitHub pull request в публичный репозиторий может осуществить любая/ой зарегистрированная/ый участница/участник.

2. Составляющие pull requests

1. Изменения, которые собираетесь внести в чужой репозиторий,
2. Описание этих изменений.

Рекомендации по грамотному внесению pull requests расписаны в ответе ув-мого IonDen.

3. Разновидности pull requests

Все pull requests можно разделить на следующие категории:

1. Исправление багов, ошибок, конфликтов с другими приложениями,
2. Добавление новых функций, возможностей,
3. Рефакторинг, стилевые правки. Если владелица/владелец репозитория не значительно хуже Вас разбирается в коде репозитория, лучше не злоупотреблять pull requests данной категории.

4. Дополнительная ссылка

2. Как сделать и принять pull request при помощи hub

1. Что такое hub?

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

git clone https://github.com/Kristinita/SashaSublime.git 

В hub команда выглядит проще:

hub clone Kristinita/SashaSublime 

Полный список команд hub, и что они упрощают, см. в документации hub.

На момент написания ответа (ноябрь 2016) hub работает только с GitHub, но не BitBucket или прочими ресурсами для хранения кода. Для пользователей Windows доступна установка через пакетный менеджер Chocolatey — cinst hub -y .

2. Зачем использовать hub?

Фиксить мелкие баги и опечатки, а затем сделать pull-request проще через веб-интерфейс GitHub. Однако если Ваши изменения довольно значительны, лучше клонировать репозиторий к себе на компьютер по следующим причинам:

• IDE/продвинутые текстовые редакторы предоставляют значительно больше возможностей для работы с кодом в сравнении с редактированием в вебе;
• Могут понадобиться разного рода тесты, недоступные при редактировании в веб-интерфейсе;
• Для многих предпочтительнее работать в терминале.

Итак, вы решили клонировать репозиторий. hub упрощает:

• Клонирование удалённого репозитория; рассмотрено в п. 2.1 данного ответа;
• Форк; достаточно ввести в терминал hub fork ;
• pull request; после того, как Вы запушили изменения в свой форк, достаточно ввести в терминал hub pull-request .

3. Настройка hub перед использованием

1. Создайте пользовательскую переменную среды GIT_EDITOR , — это сделать просто при помощи Rapid Environment Editor, — значением для которой будет путь к исполняемому файлу Вашего редактора, в котором Вам удобно писать pull request message, — описание Вашего pull request, — при необходимости добавив аргументы командной строки. Например, у меня для Sublime Text значение вышло следующим:

"D:\Sublime Text 3 x64\sublime_text.exe" -n -w 

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

1. При использовании hub в Windows и открытии редактируемых файлов в Sublime Text могут возникнуть проблемы с pull requests от имени администратора. Поскольку это не первая моя проблема, связанная с UAC, а толку от него не вижу, я отключил у себя контроль учётных записей.
2. Комментарии — текст под сообщением во вкладке PULLREQ_EDITMSG — по умолчанию выделяются #октоторпами# . Но когда Вы внесёте pull request в чужой репозиторий, то обнаружите, что текст под сообщением отобразится как заголовки, а не комментарии.

git config --global core.commentChar % 

Отныне комментариям во вкладке PULLREQ_EDITMSG будут предшествовать символы %процента% , после внесения pull request комментариев не будет видно как визуально, так и в исходном коде описания к pull request.

При необходимости резервных копий или синхронизации пользовательской конфигурации файлов git узнать, где хранятся конфигурационные файлы git, начиная с версии 2.8 можно командой:

git config --list --show-origin 

Например, у меня в Windows 10 путь к файлу, где хранится данная настройка для комментариев, оказался следующим:

file:C:/Users/SashaChernykh/.gitconfig core.commentchar=% 

Если Ваша проблема отлична от расписанных здесь, и её разрешения не получается найти поисками Google и по репозиторию; попробуйте ещё раз воспроизвести проблему, перед введением команд hub послав в терминал следующую команду:

set HUB_VERBOSE=1 

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

4. Пример создания pull request через hub

Сделаем посредством PowerShell и hub pull request в репозиторий https://github.com/LightAlf/bioRepo1. Помимо вышеперечисленных команд hub в примере используются также команды git, о предназначении которых можно узнать, например, из данного или этого ресурсов на русском.

PS E:\> hub clone LightAlf/bioRepo1 Cloning into 'bioRepo1'. remote: Counting objects: 16, done. remote: Total 16 (delta 0), reused 0 (delta 0), pack-reused 16 Unpacking objects: 100% (16/16), done. PS E:\> cd bioRepo1 PS E:\bioRepo1> Invoke-Item README.MD # В Вашем редакторе открывается файл README.MD → вносите в него изменения → сохраняете файл. PS E:\bioRepo1> git add . PS E:\bioRepo1> git commit -m "Тестирование pull-request посредством hub" [master 839c146] Тестирование pull-request посредством hub 1 file changed, 2 insertions(+) PS E:\bioRepo1> hub fork Updating Kristinita From https://github.com/LightAlf/bioRepo1 * [new branch] discuss -> Kristinita/discuss * [new branch] master -> Kristinita/master new remote: Kristinita PS E:\bioRepo1> git checkout -b SashaGoddess Switched to a new branch 'SashaGoddess' PS E:\bioRepo1> git push Kristinita SashaGoddess Counting objects: 3, done. Delta compression using up to 4 threads. Compressing objects: 100% (3/3), done. Writing objects: 100% (3/3), 471 bytes | 0 bytes/s, done. Total 3 (delta 0), reused 0 (delta 0) To https://github.com/Kristinita/bioRepo1.git * [new branch] SashaGoddess -> SashaGoddess PS E:\bioRepo1> hub pull-request # Откроется вкладка с файлом PULLREQ_EDITMSG, как на картинке ниже → вписываете в него изменения → сохраняете файл → закрываете его. https://github.com/LightAlf/bioRepo1/pull/2 PS E:\bioRepo1> 

5. Пример принятия pull-request при помощи hub

Если pull request предложен Вам, Вы можете принять его из терминала, воспользовавшись командой hub — hub merge . Изменения будут влиты в Ваш локальный репозиторий; чтобы перенести их на удалённый, следует сделать git push . Пример, как принять pull-request. если ветка, в которую предложили сделать pull request, является веткой по умолчанию.

SashaChernykh@DESKTOP-0G54NVG MINGW32 /e/SashaChocolatey (master) # Где E:\SashaChocolatey — локальный репозиторий, в связанный с которым удалённый репозиторий был внесён pull-request $ hub merge https://github.com/Kristinita/SashaChocolatey/pull/1 # Где https://github.com/Kristinita/SashaChocolatey/pull/1 — ссылка на pull-request Merge made by the 'recursive' strategy. packages/Karens Replicator/tools/chocolateyinstall.ps1 | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) SashaChernykh@DESKTOP-0G54NVG MINGW32 /e/SashaChocolatey (master) $ hub push Counting objects: 15, done. Delta compression using up to 4 threads. Compressing objects: 100% (13/13), done. Writing objects: 100% (15/15), 1.56 KiB | 0 bytes/s, done. Total 15 (delta 8), reused 0 (delta 0) remote: Resolving deltas: 100% (8/8), completed with 3 local objects. To https://github.com/Kristinita/SashaChocolatey.git 79ebe12..5045130 master -> master 

В описании коммита по умолчанию будут ссылки на коммит, которым приниматеся pull request, и на сам pull request, а также его заголовок.

Пользовательница/пользователь GitHub, у которой/которого Вы приняли pull request, не сразу, но будет указана/указан в числе контрибьюторов Вашего репозитория.

3. Дополнительная ссылка

Будь рок-звездой пул-реквестов. Советы по код-ревью

За всю свою карьеру я изучил тысячи пул-реквестов. Из этого опыта родилось несколько советов. Я надеюсь, они помогут вам создать обучающую среду, дружелюбную к новичкам и милостивую к ревьюерам. Сначала позаботимся о новичках.

Советы для автора

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

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

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

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

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

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

Полезное код-ревью — это доброжелательное код-ревью. С этими словами перейдем к советам для ревьюеров.

Советы для ревьюера

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

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

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

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

Советы для команды

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

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

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

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

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

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

Обеспечьте стабильную сборку. Проверьте, все ли работает, если запустить проект локально. Я не знаю, что вы предпочитаете — pre-commit, статический анализ кода или тесты — но знаю, что вам просто необходимо обеспечить стабильную сборку в одно касание .

К черту совершенство. Помните, что важнее всего для разработчика — это не совершенство, а здоровая кодовая база, понятная всей (всей!) команде. Поэтому не стоит расстраиваться, когда с новичками возникают трудности; вместо этого сфокусируйтесь на общем росте и развитии, которое обеспечивает практика код-ревью.

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

Пул-реквесты — это как бы обучение по типу перекрестного опыления. Уважайте усилия контрибьюторов, поскольку контекст и диалог рулят разработкой ПО. Донесите до автора то, как искренне вы в это верите. А также помните, что.

• Ясные взаимные ожидания — это основа плодотворного сотрудничества.
• Новички могут стать основными контрибьюторами вашего проекта.
• У код-ревью есть бонусы — это отлов багов и цельный код.

И наконец.

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

Это перевод статьи Дага Аркури (Doug Arcuri). Оригинальная статья: Be a Rock Star at Pull Requests. Tips for a successful collaborative code review .

Я сохранила все ссылки Аркури из оригинальной статьи. Ссылки по github milestones и SLA — от меня.

Любая критика перевода — велкам!

Как сделать код-ревью быстрее и эффективнее

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

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

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

Как избежать таких ситуаций? Как сделать пул-реквест проще и понятнее для ревьюера и оптимизировать весь процесс?

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

Категории изменений

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

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

1. Функциональные изменения.
2. Структурный рефакторинг — изменения классов, интерфейсов, методов, перемещения между классами.
3. Простой рефакторинг — может быть выполнен с помощью IDE (например, извлечение переменных/методов/констант, упрощение условий).
4. Переименование и перемещение классов — реорганизация пространства имен.
5. Удаление неиспользуемого (мертвого) кода.
6. Исправления code style.

Стратегии ревью

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

1. Изменение функционала: решение бизнес-задач и дизайн системы.
2. Структурный рефакторинг: обратная совместимость и улучшение дизайна.
3. Примитивный рефакторинг: улучшение читабельности. Эти изменения в основном можно сделать при помощи IDE (например, извлечение переменных/методов/констант и прочее).
4. Переименование/перемещение классов: улучшилась ли структура пространства имен?
5. Удаление неиспользуемого кода: обратная совместимость.
6. Исправления code style: чаще всего мерж пул-реквеста происходит сразу же.

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

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

При проверке остальных категорий в 99 % случаев мерж происходит сразу же.

1. Простой рефакторинг. Код стал более читабельным? — мержим.
2. Переименование/перемещение классов. Класс был перемещен в лучшее пространство имен?— мержим.
3. Удаление неиспользованного (мертвого) кода — мержим.
4. Исправления code style или форматирования — мержим. Ваши коллеги не должны проверять это во время код-ревью, это задача линтеров.

Почему нужно разделять изменения по категориям?

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

Что точно не стоит смешивать

Переименование/удаление класса и его рефакторинг. Здесь мы сталкиваемся с Git, который не всегда правильно понимает такие изменения. Я имею в виду масштабные изменения, когда меняется много строк. Когда вы рефакторите класс, а затем перемещаете его куда-то, Git не воспринимает это как перемещение. Вместо этого Git интерпретирует эти изменения как удаление одного класса и создание другого. Это приводит к куче вопросов во время код-ревью. И автора кода спрашивают, почему он написал этот уродливый код, хотя на самом деле этот код был просто перемещен из одного места в другое с небольшими изменениями.

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

Любые механические изменения + любые изменения, произведенные человеком. Под «механическими изменениями» я подразумеваю любое форматирование, выполненное с помощью IDE или генерации кода. Например, мы применяем новый code style и получаем изменений на 3000 строк. И если мы смешаем эти изменения с какими-либо функциональными или любыми другими изменениями, произведенными человеком, мы заставим ревьюера мысленно классифицировать эти изменения и рассуждать: это изменение, произведенное компьютером, — его можно пропустить, а это изменение, сделанное человеком, — его нужно проверить. Так ревьюер тратит очень много дополнительного времени на проверку.

Пример

Вот пул-реквест с функцией метода, который аккуратно закрывает клиентское соединение с Memcached:

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

• функциональные (новый код),
• рефакторинг (создание/перемещение классов),
• исправления code style (удаление лишних док-блоков).

В результате ревьюер должен просмотреть весь код и

• проверить, что рефакторинг в порядке;
• проверить, правильно ли реализован новый функционал;
• определить, было ли это изменением произведено автоматически IDE или человеком.

1. Рефакторинг: извлечение класса

Здесь всего два файла. Ревьюер должен проверить только новый дизайн. Если все в порядке — мержим.

2. Следующим шаг — тоже рефакторинг, мы просто перемещаем два класса в новое пространство имен

Такой пул-реквест довольно просто проверять, он может быть смержен сразу.

3. Удаление лишних блоков док-блоков

Здесь ничего интересного. Мержим.

4. Сам функционал

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

Заключение

Практическое правило:

Не создавайте огромных пул-реквестов со смешанными категориями изменений.

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

И всегда выполняйте следующие шаги до отправки пул-реквеста:

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

От редакции: Сергей много пишет интересного про программирование и PHP, а мы иногда что-то переводим: сервер потокового видео, рендеринг HTML файлов. Смело задавайте ему вопросы в комментариях к этой статье — он ответит!

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

• Блог компании Skyeng
• Программирование
• Проектирование и рефакторинг
• Управление разработкой

Что такое пул-реквесты и зачем они нужны?

Если вы еще новичок в мире Git и тесно связанных с ним платформ (например, GitHub или GitLab), то вы могли и не слышать таких терминов, как пул-реквест (pull request) или мерж-реквест (merge request). И даже если что-то такое слышали, то можете не знать, что означают эти термины и зачем нужны эти самые «реквесты».

Примечание. В статье я буду использовать термин «пул-реквест», но по сути это то же самое, что мерж-реквест, только последний используется на GitLab.

Пул-реквесты помогают командам создавать программы и распространять их. Чтобы вникнуть в саму идею, придется немного напрячься, но я уверен, что дело того стоит. Моя цель — помочь вам познакомиться с пул-реквестами и рассказать, какое место они занимают в процессе разработки ПО.

Что такое пул-реквест?

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

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

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

Вот как выглядит пул-реквест с простым описанием и ссылкой на issue (проблему) на GitHub:

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

Коммуникация

По сути пул-реквесты облегчают процесс совместной работы с другими людьми. Они позволяют сделать прозрачной коммуникацию между авторами и ревьюерами путем показа дифф-ов (diffs), коммитов (commits) и комментариев, поясняющих изменения.

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

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

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

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

Автоматизация

Поскольку пул-реквесты приобрели огромную популярность в сообществе разработчиков, GitHub и другие подобные платформы создали обширный набор вебхуков (webhooks), спроектированных на основе GitHub flow. Эти вебхуки делают возможной автоматизацию работы. В наши дни распространена практика, когда задачи непрерывной интеграции выполняются при каждом коммите, и поэтому являются частью пул-реквеста. По своему опыту могу судить, что это одно из самых подходящих мест для автоматизации. Речь идет не только о запуске автоматизированных тестов. Из изменений в пул-реквесте можно разворачивать целые окружения, чтобы проверить, гладко ли все прошло.

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

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

Проверки статуса

Последнее большое преимущество пул-реквестов это концепция проверок статуса (status checks). Проверки статуса это просто набор задач, выполняемых для каждого коммита в пул-реквесте, и выдающих результат «успех» (success) или «провал» (failure). Это буквально чек-листы для проверки того, готовы ли изменения к отправке в кодовую базу.

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

Стоит также остановиться на теме код-ревью. Поскольку пул-реквесты сильно улучшают возможности коммуникации и сотрудничества, естественно, что многие команды применят их в код-ревью. Таким образом прямо со страницы пул-реквеста можно осуществлять менеджмент ревьюеров, ревью и статуса запросов (одобрено или нет). Во многих крупных проектах есть даже автоматическая процедура добавления отдельных пользователей или групп к пул-реквесту — в зависимости от файлов, которые были изменены. Если хотите пример, посмотрите документацию CODEOWNERS.

Итоги

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

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

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