Что такое пул реквест
Что такое пул-реквесты и зачем они нужны?
Перевод статьи «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.
Итоги
Если брать коротко, пул-реквест это просто запрос на внедрение изменений из одной ветки в другую. Несмотря на простоту концепции, пул-реквесты являются очень мощным инструментом. Именно поэтому они стали важной частью современной разработки. Пул-реквесты облегчают задачи непрерывной интеграции, код-ревью и проверки статуса, а все вместе это позволяет поддерживать высокий уровень качества кода.
Если раньше репозиторий был просто местом, где хранится код, то с появлением пул-реквестов он стал местом, где хранятся знания об этом коде.
Также пул-реквесты играют большую роль в процессе обучения. Некоторые из самых важных уроков, касающихся разработки программ, я получил в фидбэках терпеливых ревьюеров моих пул-реквестов.
Как сделать первый пул-реквест на GitHub
Перевод статьи «How to make your first pull request on GitHub».
Что такое форк?
Когда нам нравится чей-то репозиторий и мы хотели бы иметь его в собственном аккаунте на GitHub, мы делаем форк («вилку») этого репозитория, чтобы иметь возможность работать с ним отдельно.
Когда мы делаем форк репозитория, мы получаем экземпляр всего репозитория, со всей его историей. После форка мы можем делать с ним все, что угодно: оригинальная версия при этом не будет задета.
Что такое пул-реквест?
Пул-реквесты нужны. Когда мы хотим принять участие в групповой разработке проектов с открытым исходным кодом.
Например, пользователь Павел делает форк репозитория ThanoshanMV (автора статьи, — прим. перев.) и вносит изменения в свой экземпляр. После этого Павел отсылает пул-реквест ThanoshanMV, который может либо принять его, либо отклонить. По сути это что-то вроде письма «Не будете ли вы так любезны, уважаемый ThanoshanMV, внести мои изменения в свой оригинальный репозиторий?»
Как можно стать контрибьютором проекта?
Участие в проекте с открытым исходным кодом не обязательно предполагает работу именно с кодом. Контрибьютором (участником) можно стать и другими способами, некоторые из них описаны ниже.
Давайте создадим наш первый пул-реквест!
1. Форк репозитория
Чтобы сделать форк репозитория, нужно нажать кнопку «Fork» в верху страницы. Таким образом вы создадите экземпляр всего этого репозитория в своем аккаунте.
2. Клонирование репозитория
Когда репозиторий уже есть в вашем аккаунте, вы можете клонировать его на свою машину и в дальнейшем работать с ним локально.
Чтобы клонировать репозиторий, нажмите кнопку «clone» и скопируйте ссылку.
Откройте терминал и запустите следующую команду. С ее помощью репозиторий будет клонирован на вашу машину.
Теперь у вас есть копия ветки master основного онлайн-репозитория проекта.
Переходим в клонированную директорию:
3. Создание ветки
При работе с репозиторием хорошей практикой считается создание отдельной ветки для внесения изменений, причем это не зависит от размеров проекта.
Имя ветки должно быть коротким и отражать те изменения, которые вы вносите.
Создадим ветку при помощи команды git checkout:
4. Внесение изменений и коммит
Внесите необходимы изменения в проект и сохраните их. Затем запустите команду git status: вы увидите внесенные изменения.
Добавьте эти изменения в только что созданную ветку при помощи команды git add:
Теперь вы можете сделать коммит этих изменений при помощи команды git commit:
5. Отправка изменений на GitHub
Чтобы отправить изменения на GitHub (сделать push), нужно определить имя удаленного репозитория.
Имя данного удаленного репозитория — «origin».
После определения имени можно безопасно отправить изменения на GitHub.
6. Создание пул-реквеста
Перейдите в свой репозиторий на GitHub. Там есть кнопка «Compare & pull request» — кликните ее.
Введите необходимые детали относительно того, что именно вы сделали (чтобы поставить ссылку на issues, возмользуйтесь знаком «решетки»). После этого можно нажать кнопку подтверждения внизу.
Поздравляю! Вы создали свой первый пул-реквест. Если его примут, вы получите уведомление по электронной почте.
7. Синхронизация вашего форка с основной веткой
Прежде чем создавать пул-реквест в оригинальный репозиторий, нужно синхронизировать свой экземпляр этого репозитория с оригинальным.
Даже если вы не собираетесь отправлять пул-реквест в оригинальный репозиторий, все равно лучше синхронизироваться с ним. Со времени создания форка в оригинальном репозитории могли добавиться новые фичи, а также могли быть исправлены какие-то баги.
Проделайте следующие действия, чтобы обновить свой репозиторий и внести соответствующие изменения в свою ветку master:
1. Для начала, проверьте, в какой ветке вы находитесь.
Вы получите список всех веток, причем активная будет подсвечена зеленым.
2. Переключитесь в ветку master.
3. Добавьте оригинальный репозиторий в качестве upstream-репозитория.
Чтобы вытащить изменения из оригинального репозитория и перенести их в свою версию, нужно добавить оригинальный git-репозиторий в качестве upstream-репозитория.
Здесь [HTTPS] это url, который нужно скопировать из основного репозитория.
4. Fetch репозитория
Заберите (fetch) все изменения из оригинального репозитория. Коммиты, сделанные в оригинальном репозитории, будут сохранены в локальной ветке под названием upstream/master.
5. Слейте изменения
Слейте (merge) изменения из upstream/master с вашей локальной веткой master. Таким образом главная ветка вашего форка репозитория синхронизируется с upstream-репозиторием без потери ваших локальных изменений.
6. Отправьте изменения на GitHub
На этом этапе ваша локальная ветка синхронизирована с веткой master оригинального репозитория. Если вы хотите обновить свой GitHub-репозиторий, нужно отправить в него изменения.
Примечание. После синхронизации ветки master вашего форка вы можете при желании удалить remote. Но в будущем вам еще придется обновлять/синхронизировать ваш репозиторий, поэтому лучше его сохранить.
8. Удаление ненужной ветки
Ветки создаются с какими-то конкретными целями. Когда цель достигнута, необходимость в ветке отпадает, поэтому ее можно удалить.
Вы можете удалить и версию этой ветки на GitHub.
Итоги
GitHub это мощный инструмент для контроля истории версий. Каждый может стать контрибьютором проекта с открытым исходным кодом. Делается это путем отправки пул-реквестов.
Чтобы стать контрибьютором, не обязательно писать код: есть и другие способы принять участие в проекте.
Наконец, я хотел бы также сказать, что не стоит переживать, если ваши пул-реквесты отклонят. Мейнтейнеры тратят много времени на улучшение своих проектов и они, безусловно, лучше знают эти проекты, чем вы. Поэтому не стоит переживать, если они решат не вливать в свой проект ваши изменения.
Pull Request Preview – что это такое и с чем его едят
Работа над крупным проектом – это всегда командная работа. И в этой команде каждый программист занимается реализацией отдельной задачи, работая в своей функциональной ветке GitHub, GitLab, Bitbucket или любого другого репозитория.
После того как разработчик решит задачу, необходимо выполнить слияние результатов с основной веткой проекта для того, чтобы другие участники команды могли использовать разработанные им функции. Содержимое основной ветки собирается и доставляется в production, став достоянием коллег из других отделов или заказчиков.
Но это если не брать в расчет такой этап работы, как Pull Request…
Что такое Pull Request и зачем он нужен?
Как я уже отметил выше, каждый программист в команде занимается разработкой в своей функциональной ветке. Она не затрагивает главную ветку, поэтому изменения, внесенные в код конкретным разработчиком, не появляются в приложении автоматически.
Когда разработчик заканчивает работу над функцией или исправлением бага, он должен уведомить об этом других членов команды, чтобы те провели аудит кода.
По сути, такое уведомление – это и есть пул-реквест. То есть запрос на слияние написанного разработчиком кода с основной веткой для дальнейшей публикации.
Но пул-реквест – это не просто оповещение. Это целая платформа для обсуждения и дальнейшей доработки кода другими членами команды. При каждом пул-запросе формируется отдельная страница, где коллеги разработчика могут оставить комментарии или внести дополнительные изменения в его код.
Если другие разработчики заметят в коде ошибки, то смогут исправить их или предложить более элегантные варианты реализации ожидаемой функции. Если же все в порядке, то код из ветки разработки объединяют с основной (совершают так называемый мердж), а потом публикуют его (эту процедуру называют деплоем), и он попадает непосредственно в приложение. Но не факт, что все будет в порядке…
Почему одного пул-реквеста недостаточно?
Разработчикам приходится создавать отдельные структурные элементы продукта, минимально коммуницируя с другими сотрудниками команды. Да, за качеством кода следят программисты, и они действительно могут обнаружить логические ошибки во внедряемой функции или проконтролировать корректность оформления и структурированность кода.
Но маркетолог, менеджер или заказчик приложения может ничего не понимать в языках программирования. Поэтому он не в силах адекватно оценить, насколько хороша та реализация, которую предлагает разработчик, как она повлияет на текущее состояние продукта, соответствует ли предложенный код техническому заданию заказчика, нужно ли что-то скорректировать, дополнить и т.п. Приходится ждать непосредственного запуска новой функции или сервиса, чтобы все могли оценить его в полной мере. До этого момента коллеги программистов слепо надеются на то, что итоговый результат будет соответствовать общим ожиданиям.
Такой подход негативно сказывается на скорости разработки и периодичности появления новых функций, потому что отсутствие возможности полноценно оценить код всей командой увеличивает временные промежутки между внесением правок в код и последующим тестированием этих правок после деплоя.
В итоге это сильно усложняет процесс разработки в целом, потому что далеко не всегда тот код, что успешно прошел проверку на этапе пул-реквеста, становится тем кодом, который нравится заказчику и другим участникам команды.
И тогда программистам приходится начинать сначала или радикально менять написанный код. Из-за этого увеличивается срок сдачи проекта и затраты, а также нарастает необходимость в возможности проверить Pull Request не только отделом разработки.
На помощь приходит Pull Request Preview
У маркетологов, менеджеров, заказчиков и прочих членов команды, не связанных с разработкой, появилась возможность взглянуть на новые функции или изменения в коде до их внедрения в продукт.
Функция Pull Request Preview – это как деплой, но только в закрытое (временное) окружение, а не в production. Вы можете в полной мере оценить все обновления, что предлагают программисты, не зная кода. Попользоваться ими, проверить на практике или попробовать сломать. И все это – до объединения ветки разработки с основной веткой, то есть без угрозы для действующего продукта.
Такую функцию предлагает Hostman – хостинг для упрощенной публикации сайтов, приложений, баз данных и других продуктов прямо из GitHub или GitLab.
Принцип работы Pull Request Preview в Hostman
Хостинг-провайдер Hostman, партнер Timeweb, недавно запустил функцию Pull Request Preview для своих пользователей. И она позволяет без лишних движений проводить основательное тестирование внедряемых функций всей командой еще до деплоя.
Pull Request Preview в Hostman
Почему я делаю акцент на «без лишних движений»? Потому что все происходит в автоматическом режиме:
Как работает Pull Request
Как работает Pull Request Preview
Рабочий процесс никак не затрагивает программистов. Они действуют по той же схеме, что и раньше, а другие сотрудники получают новые возможности:
Вместо заключения
Возможность до мерджа всем штатом сотрудников опробовать продукт, найти в нем ошибки и принять решение о дальнейшем внедрении – отличное подспорье для бизнеса.
Pull Request Preview позволит ускорить процесс разработки, сократит количество времени, которое уходит на тестирование продукта, что повлечет за собой сокращение потраченных на разработку человеко-часов и бюджета компании. В итоге это позволит реализовывать даже самые смелые задумки (новые функции, масштабную смену дизайна) в короткие сроки и поможет «обогнать конкурентов на поворотах». Там, где другие компании находятся в невыгодном положении, тратя много времени на работу с каждым пул-реквестом, бизнес, использующий Pull Request Review, сможет быстрее принимать решения и идти в ногу с потребностями рынка.
Впрочем, оценить все прелести Pull Request Preview можно самостоятельно. Hostman предлагает новым клиентам бесплатно создать до трех статических сайтов, подключить GitHub и попробовать Pull Request Preview, чтобы на практике увидеть, как работает эта функция и как сильно она может помочь вашему бизнесу.
Что такое pull request?
Что такое «пул реквест» (pull request), который на GitHub, и как его применить?
4 ответа 4
К вышесказанному можно добавить следующее. Далеко не все пулл-реквесты принимаются разработчиками. Тут нужно соблюсти ряд правил:
Пулл-реквест (ПР) должен быть хорошо оформлен и содержать исчерпывающее описание.
Очень важно соблюдать Code Style того проекта, для которого вы делаете ПР. Пусть даже он кажется вам противоестественным (например вы всегда делаете отступы в виде 4 пробелов, а в проекте табы).
Не нужно бояться делать ПР-ы, ведь помочь можно даже в мелочи. Например вы заметили ошибку перевода в readme файле или вам кажется что какое-то описание фичи можно более понятно перефразировать.
На гитхабе миллионы проектов, живущие исключительно на энтузиазме создателей, хорошие ПР-ы очень хорошо подстегивают этот энтузиазм)
еще добавки к вышесказанному: возможный (я им пользуюсь) механизм работы с репами/pr:
git clone https://github.com/ваш_юзернейм/sqlpp11.git
git remote add upstream https://github.com/rbock/sqlpp11.git (т.е. мы добавляем псевдоним upstream для оригинального репозитория, мы не можем добавлять в него изменения, но можем их получать)
теперь вы правите файлы в вашем origin, в вашей ветке, пушите их в свой форк гитхаба (origin), откуда и делаете pull-request
при этом вы можете сделать git merge/pull/fetch upstream с оригинального репозитория (upstream)
если в upstream настроена интеграция типа travis-ci (как в моем примере), лучше не делать пулл-реквесты, пока не настроите travis-ci для своего репозитория и ваши билды не будут работать правильно (чтобы не мучать мэйнтейнера upstream бессмысленными сообщениями о неудачных сборках в пулл-реквесте)
1. Что такое pull request?
1. Определение
pull request — предложение изменения кода в чужом репозитории.
Вы делаете форк чужого репозитория (который иногда и сам может быть форком) → производите изменения в своём форке → посредством pull request предлагаете изменения владельцам репозитория, чей форк Вы сделали. На GitHub pull request в публичный репозиторий может осуществить любая/ой зарегистрированная/ый участница/участник.
2. Составляющие pull requests
Рекомендации по грамотному внесению pull requests расписаны в ответе ув-мого IonDen.
3. Разновидности pull requests
Все pull requests можно разделить на следующие категории:
4. Дополнительная ссылка
2. Как сделать и принять pull request при помощи hub
1. Что такое hub?
hub — консольное приложение, упрощающее введение команд git, обёртка для git. Например, чтобы клонировать репозиторий, используя git, мы должны ввести в терминал:
В hub команда выглядит проще:
Полный список команд hub, и что они упрощают, см. в документации hub.
2. Зачем использовать hub?
Фиксить мелкие баги и опечатки, а затем сделать pull-request проще через веб-интерфейс GitHub. Однако если Ваши изменения довольно значительны, лучше клонировать репозиторий к себе на компьютер по следующим причинам:
Итак, вы решили клонировать репозиторий. hub упрощает:
3. Настройка hub перед использованием
Если путь к исполняемому файлу содержит пробелы, во избежание багов, лучше заключить его в кавычки.
При необходимости резервных копий или синхронизации пользовательской конфигурации файлов git узнать, где хранятся конфигурационные файлы git, начиная с версии 2.8 можно командой:
Например, у меня в Windows 10 путь к файлу, где хранится данная настройка для комментариев, оказался следующим:
Если Ваша проблема отлична от расписанных здесь, и её разрешения не получается найти поисками Google и по репозиторию; попробуйте ещё раз воспроизвести проблему, перед введением команд hub послав в терминал следующую команду:
В терминале появится отладочная информация. Если и по ней не получилось разрешить проблему, создайте багрепорт в issue tracker hub, приложив к сообщению вывод Вашего терминала вместе с отладочной информацией.
4. Пример создания pull request через hub
Сделаем посредством PowerShell и hub pull request в репозиторий https://github.com/LightAlf/bioRepo1. Помимо вышеперечисленных команд hub в примере используются также команды git, о предназначении которых можно узнать, например, из данного или этого ресурсов на русском.
5. Пример принятия pull-request при помощи hub
В описании коммита по умолчанию будут ссылки на коммит, которым приниматеся pull request, и на сам pull request, а также его заголовок.
Пользовательница/пользователь GitHub, у которой/которого Вы приняли pull request, не сразу, но будет указана/указан в числе контрибьюторов Вашего репозитория.