Пулл реквест что это
Pull request’ы на GitHub или Как мне внести изменения в чужой проект
По просьбе tulskiy делаю вольный перевод частей официальной документации GitHub’а Fork A Repo и Send pull requests.
Итак, что же такое «запрос на включение (сделанных вами изменений)» (именно так я перевёл pull request)? В официальной документации гитхаба говорится следующее:
Pull request’ы позволяют вам рассказать другим о тех изменениях, которые вы разместили в своём GitHub-репозитории. Как только pull request отправлен, заинтересованные стороны рассматривают ваши изменения, обсуждают возможные правки или даже добавляют дополняющие коммиты, если нужно.
Немного о моделях совместной разработки
Делаем копию репозитория
Рассматривая первую модель разработки, необходимо иметь свою копию изначального репозитория, в которой и будет вестись работа, и изменения из которой и будут предлагаться затем автору изначального репозитория.
В рамках руководства, будем считать, что мы работаем над репозиторием Spoon-Knife пользователя octocat, а ваше имя пользователя — username.
Сделать это очень просто: на странице репозитория имеется кнопочка «Fork», которую и следует нажать. 
После чего, эту свою копию уже можно «стянуть» на свой компьютер:
Склонированный репозиторий имеет одну привязку к удалённому репозиторию, названную origin, которая указывает на вашу копию на GitHub, а не на оригинальный репозиторий, чтобы отслеживать изменения и в нём, вам нужно будет добавить другую привязку, названную, например, upstream.
Делаем работу
Итак, в этой точке мы уже можем править код и делать коммиты. Если вы сделали все предыдущие шаги, чтобы потом вернуть ваши изменения в оригинальный репозиторий, то я настоятельно советую делать всю работу в отдельной тематической ветви разработки. Полезность этого станет ясна на этапе посылки pull request’а. Пускай она будет называться feature.
Вот, теперь творите добро (и пусть оно будет выражаться в коммитах).
Как только вы сделали работу (или её часть), отправьте её в свою копию репозитория на GitHub:
Возвращаем изменения: Pull request
Итак, всё сделано. Вы написали код, он у вас в ветви feature как у вас на компьютере, так и на GitHub’е. Осталось только «заслать» его в оригинальный репозиторий.
Идите на страницу вашей копии репозитория на GitHub, выбирайте ветвь feature и жмите кнопку Pull Request. 
Далее вы попадёте на предпросмотровую страницу, на которой сможете ввести название и описание ваших изменений (название потом попадёт в описание мёрдж-коммита и станет достоянием общественности, учтите это).
Там же вы можете посмотреть, какие коммиты попали в пулл реквест:
А так же общий diff всех изменений в пулл реквесте:
По умолчанию, пулл реквесты считаются основанными на самой часто интегрируемой ветви родительского репозитория. В этом случае username/Spoon-Knife был скопирован с octocat/Spoon-Knife, так что pull request считается основанным на ветке master репозитория octocat/Spoon-Knife. В большинстве случаев, это будет корректно, но если не так, то вы можете нажать на кнопку «Change Commits»
Вы попадёте в форму выбора базовой и исходной ветвей:
Слева выбираете в какую ветку будут вливаться изменения в родительском репозитории, справа — какие изменения будут браться с вашего репозитория. По примеру: справа octocat/Spoon-Knife/master, слева username/Spoon-Knife/feature. Здесь вы можете указывать не только ветки, но так же теги и id отдельных коммитов в соответствующем репозитории.
ВАЖНО: Договоритесь с владельцем «родительского» репозитория, в какую ветку будете вливать изменения (он может написать это в README)
Изменение базового репозитория меняет и список людей, кто получит уведомление о пулл реквесте. Каждый, кто имеет право «на запись» в базовый репозиторий, получит письмо и увидит уведомление на главной GitHub’а, в следующий раз, как на него зайдёт.
Как только список коммитов вас удовлетворит, нажмите кнопку Update Commit Range.
Когда вы ввели название и описание и перепроверили список коммитов и изменения в файлы, попавшие в пулл реквест, нажмите кнопку Send pull request. Пулл реквест будет создан незамедлительно.
Что дальше?
Следите за вашим пулл-реквестом. Что прокомментируют люди, что скажет мэйнтэйнер, примет или нет ваш пулл реквест.
Когда ваш pull request примут, не забудьте слить изменения в свой репозиторий (или удалить его, если больше не нужен):
Так же можно удалить ветку, в которой велась разработка:
Что следует делать, если работа заняла большое время и оригинальный репозиторий успел уйти вперёд?
Можно просто влить изменения из оригинального репозитория к себе:
Однако хозяину оригинального репозитория или, может быть, даже вам, не понравится наличие мёрж-коммитов и коммитов из master’а в списке коммитов на пулл. В таком случае вам стоит воспользоваться git rebase.
Прочитать про то, как работает rebase можно в официальном руководстве. Там имеются и очень понятные иллюстрации. Так же есть статья в помощи GitHub.
ВНИМАНИЕ: Пожалуйста, учтите, что git rebase меняет id коммитов! Поэтому, все действия с этой командой стоит выполнять только на локальном репозитории, до того, как эти коммиты станут общедоступны, т.е. до того, как вы их push’нули на гитхаб.
Если вы хозяин: Как принять pull request
Если пулл реквест удовлетворяет всем условиям, то кто-либо с правом «на запись» (т.е. может сделать push) в целевой репозиторий, должен принять pull request одним из многих методов. Ниже описаны три наиболее популярных метода:
Auto Merge (автослияние)
Во многих случаях можно попросить github автоматически принять пулл реквест, используя большую зелёную кнопку Merge Pull Request, которая сама вольёт изменения, создаст мёрж-коммит и закроет пулл реквест.
Подробнее можно почитать в этом хабратопике: Кнопка слияния на GitHub.
Fetch and Merge (скачать и слить)
Основной метод вливания изменений. Он требует добавления remote, ведущего к репозиторию человека, отправившего pull request, скачивания изменений с этого репозитория, объединения нужной ветви, исправления конфликтов и выгрузки обновлённой ветви обратно в исходный репозиторий:
Patch and Apply (пропатчить и принять)
Предыдущий метод работает хорошо, когда вы работаете в команде или постоянно принимаете изменения от одной и той же группы людей. Другой метод немного быстрее в единичных случаях при использовании git-am.
Закрытие пулл реквеста
Запросы на пулл автоматически закрываются, когда запрошенные коммиты вливаются в репозиторий назначения. При этом генерируется событие, информирующее всех участников разработки, что пулл реквест был принят и влит в основную ветвь.
Так же возможно вручную закрыть пулл реквест в случае, если он был отклонён. Иногда это необходимо в случаях, когда изменения были приняты с помощью git-cherry-pick или другого механизма, который не позволяет обнаружить факт слияния (merge).
Что такое пул-реквесты и зачем они нужны?
Перевод статьи «What’s the Point of Pull Requests Anyway?»
Если вы еще новичок в мире 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.
Итоги
Если брать коротко, пул-реквест это просто запрос на внедрение изменений из одной ветки в другую. Несмотря на простоту концепции, пул-реквесты являются очень мощным инструментом. Именно поэтому они стали важной частью современной разработки. Пул-реквесты облегчают задачи непрерывной интеграции, код-ревью и проверки статуса, а все вместе это позволяет поддерживать высокий уровень качества кода.
Если раньше репозиторий был просто местом, где хранится код, то с появлением пул-реквестов он стал местом, где хранятся знания об этом коде.
Также пул-реквесты играют большую роль в процессе обучения. Некоторые из самых важных уроков, касающихся разработки программ, я получил в фидбэках терпеливых ревьюеров моих пул-реквестов.
Лучший Pull Request
Относительно недавно мне посчастливилось присоединиться к команде разработки Bitbucket Server в Atlassian (до сентября он был известен как Stash). В какой-то момент мне стало любопытно, как этот продукт освещён на Хабре, и к моему удивлению, нашлось лишь несколько заметок о нём, подавляющее большинство которых на сегодняшний день уже устарело.
В связи с этим я решил опробовать себя в роли рассказчика и затронуть техническую сторону Bitbucket. Прошу не рассматривать моё намерение как попытку рекламы, ибо я совершенно не преследую эту цель. Если эта статья обнаружит интерес со стороны читателей, я буду рад развивать тему и постараюсь ответить на возникающие вопросы.
Позвольте начать с перевода статьи Тима Петтерсена «A better pull request» о том, как должен выглядеть pull request, чтобы наиболее эффективно решать возложенную на него задачу.
В любой русскоязычной технической статье, касающейся систем контроля версий (как, впрочем, большинства любых связанных с IT тем), автор сталкивается с необходимостью использования специфичных терминов, которые могут быть или не быть переведены на русский. В жизни большинство этих терминов не переводится и используется при вербальном общении «как есть», то есть, по сути, транслитерируется. В письменной же форме их, строго говоря, следует переводить, однако в этом случае термины зачастую совершенно перестают быть созвучными англоязычным версиям, что сильно затрудняет их восприятие читателями.
Мне хотелось бы пользоваться привычными названиями и в письменной речи, однако некоторые термины я не буду даже транслитерировать, поскольку, на мой взгляд, они становятся слишком корявыми, и потому оставлю их в английском написании, — прошу понять и простить. С другой стороны, я открыт критике и предложениям, поэтому если вы считаете, что есть лучший способ выразить тот или иной термин, прошу делиться этими мыслями. Спасибо.
Если вы используете Git, то наверняка пользуетесь и pull request-ами. Они в той или иной форме существуют с момента появления распределённых систем управления версиями. До того, как Bitbucket и GitHub предложили удобный веб-интерфейс, pull request мог представлять собой простое письмо от Алисы с просьбой забрать какие-то изменения из её репозитория. Если они были стóящими, вы могли выполнить несколько команд, чтобы влить эти изменения в вашу основную ветку master:
Разумеется, включать изменения от Алисы в master не глядя — это далеко не лучшая идея: ведь master содержит код, который вы собираетесь поставлять клиентам, а потому наверняка хотите внимательно следить за тем, что в него попадает. Более правильный путь, чем простое включение изменений в master, — это сначала влить их в отдельную ветку и проанализировать перед тем, как cливать в master:
Приведённая команда git diff с синтаксисом трёх точек (в дальнейшем «triple dot» git diff) покажет изменения между вершиной ветки alice/branch и её merge base — общим предком с локальной веткой master, иначе говоря, с точкой расхождения истории коммитов этих веток. В сущности, это будут ровно те изменения, которые Алиса просит нас включить в основную ветку.
git diff master. alice/master эквивалентен git diff A B
На первый взгляд, это кажется разумным способом проверки изменений pull request-а. Действительно, на момент написания статьи, именно такой алгоритм сравнения применяется в реализации pull request-ов в большинстве инструментов, предоставляющих хостинг git-репозиториев.
Несмотря на это, есть несколько проблем в использовании «triple dot» git diff для анализа изменений pull request-а. В реальном проекте основная ветка, скорее всего, будет сильно отличаться от любой ветки функциональности (в дальнейшем feature-ветка). Работа над задачами ведётся в отдельных ветках, которые по окончании вливаются в master. Когда master продвигается вперёд, простой git diff от вершины feature-ветки до её merge base уже недостаточен для отображения настоящего различия между этими ветками: он покажет разницу вершины feature-ветки лишь с одним из предыдущих состояний master.
Ветка master продвигается за счёт вливания новых изменений. Результат git diff master. alice/master не отражает этих изменений master.
Почему же невозможность увидеть эти изменения в ходе анализа pull request-а является проблемой? Тому есть две причины.
Конфликты слияния (merge conflicts)
С первой проблемой вы наверняка регулярно сталкиваетесь — конфликты слияния. Если в вашей feature-ветке вы измените файл, который в то же время был изменён в master, git diff по-прежнему будет отображать только изменения, сделанные вами в feature-ветке. Однако при попытке выполнить git merge вы столкнётесь с ошибкой: git расставит маркеры конфликтов в файлах вашей рабочей копии, поскольку сливаемые ветки имеют противоречивые изменения, — такие, которые git не в состоянии разрешить даже с помощью продвинутых стратегий слияния.
Конфликт слияния
Вряд ли кому-то нравится заниматься разрешением конфликтов слияния, но они являются данностью любой системы контроля версий, — по крайней мере, из тех, которые не поддерживают блокирование на уровне файла (которое, в свою очередь, имеет ряд своих проблем).
Однако конфликты слияния — это меньшая неприятность, с которой вы можете столкнуться при использовании «triple dot» git diff для pull request-ов, по сравнению с другой проблемой: особый тип логического конфликта будет успешно слит, но сможет внести коварную ошибку в кодовую базу.
Логические конфликты, остающиеся незамеченными во время слияния
Если разработчики модифицируют разные части одного и того же файла в разных ветках, появляется вероятность того, что они создадут такой конфликт. В некоторых случаях разные изменения, которые исправно работают по отдельности и отлично сливаются безо всяких конфликтов с точки зрения системы контроля версий, могут внести логическую ошибку в код, будучи применёнными вместе.
Это может произойти различными путями, однако самым распространённым является вариант, когда два разработчика случайно замечают и исправляют одну и ту же ошибку в двух разных ветках. Представьте, что приведённый ниже код на javascript вычисляет стоимость авиабилета:
Здесь содержится очевидная ошибка: автор забыл включить в расчёт таможенный сбор!
Теперь представьте двух разработчиков, Алису и Боба, каждый из которых заметил эту ошибку и исправил её независимо от другого в своей ветке.
Алиса добавила строку для учёта customsFee перед immigrationFee:
Боб сделал аналогичную правку, однако поместил её после immigrationFee:
Поскольку в каждой из этих веток были изменены разные строки кода, слияние обеих с master пройдёт успешно одно за другим. Однако теперь master будет содержать обе добавленные строки, а значит, клиенты будут дважды платить таможенный сбор:
(Это, разумеется, надуманный пример, однако дублированный код или логика могут вызвать весьма серьёзные проблемы: к примеру, дыру в реализации SSL/TLS в iOS.)
Предположим, что вы сначала слили в master изменения pull request-а Алисы. Вот что показал бы pull request Боба, если бы вы использовали «triple dot» git diff:
Поскольку вы анализируете изменения по сравнению с общим предком, нет никакого предупреждения об угрозе ошибки, которая случится, когда вы нажмёте на кнопку слияния.
На самом же деле, при анализе pull request-а вы хотели бы видеть, как master изменится после слияния изменений из ветки Боба:
Здесь явно обозначена проблема. Рецензент pull request-а, будем надеяться, заметит дублированную строчку и уведомит Боба о том, что код нужно доработать, и тем самым предотвратит попадание серьёзной ошибки в master и, в конечном счёте, в готовый продукт.
Таким образом мы решили реализовать показ изменений в pull request-ах в Bitbucket. При просмотре pull request-а вы видите, как на самом деле будет выглядеть результат слияния (т.е. фактически, результирующий коммит). Чтобы осуществить это, мы производим настоящее слияние веток и показываем разницу между получившимся коммитом и верхушкой целевой ветки pull request-а:
git diff C D, где D — это коммит, получившийся в результате слияния, показывает все различия между двумя ветками
Если вам интересно, я разместил одинаковый репозиторий на нескольких хостингах, чтобы вы сами смогли увидеть описанную разницу между алгоритмами сравнения:
Продвижение веток
Во-первых, коммит слияния D на самом деле ещё не существует, а его создание — относительно дорогой процесс. Во-вторых, недостаточно просто создать коммит D и на этом закончить: B и C, родительские коммиты для нашего коммита слияния, могут поменяться в любое время. Мы называем изменение любого из родительских коммитов пересмотром (rescope) pull request-а, поскольку оно, по сути, модифицирует тот набор изменений, который будет применён в результате слияния pull request-а. Если ваш pull request нацелен на нагруженную ветку вроде master, он наверняка пересматривается очень часто.
Коммиты слияния создаются каждый раз, когда любая из веток pull request-а изменяется
Фактически, каждый раз когда кто-то коммитит или сливает pull request в master или feature-ветку, Bitbucket должен создать новый коммит слияния, чтобы показать актуальную разницу между ветками в pull request-е.
Обработка конфликтов слияния
Другая проблема при выполнении слияния для отображения разницы меджу ветками в pull request-е заключается в том, что время от времени вам придётся иметь дело с конфликтами слияния. Поскольку git сервер работает в неинтерактивном режиме, разрешать такие конфликты будет некому. Это ещё больше усложняет задачу, но на деле оказывается преимуществом. В Bitbucket мы действительно включаем маркеры конфликтов в коммит слияния D, а затем помечаем их при отображении разницы между ветками, чтобы явно указать вам на то, что pull request содержит конфликты:
Зелёные строки добавлены, красные — удалены, а жёлтые означают конфликт
Таким образом, мы не только заранее выявляем, что pull request содержит конфликт, но и позволяем рецензентам обсудить, как именно он должен быть разрешён. Поскольку конфликт всегда затрагивает, как минимум, две стороны, мы считаем, что pull request — это лучшее место для нахождения подходящего способа его разрешения.
Несмотря на дополнительную сложность реализации и ресурсоёмкость используемого подхода, я считаю, что выбранный нами в Bitbucket подход предоставляет наиболее точную и практичную разницу между ветками pull request-а.
Автор оригинальной статьи — Тим Петтерсен, участвовал в разработке JIRA, FishEye/Crucible и Stash. С начала 2013 года он рассказывает о процессах разработки, git, непрерывной интеграции и поставке (continuous integration/deployment) и инструментах Atlassian для разработчиков, особенно о Bitbucket. Тим регулярно публикует заметки об этих и других вещах в Twitter под псевдонимом @kannonboy.
Надеюсь, что эта статья оказалась интересной. Буду рад ответить на вопросы и комментарии.