Pull request git что это
Что такое пул-реквесты и зачем они нужны?
Перевод статьи «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
07 Марта 2016 • Михаил Панков • руководства • поддержите на Patreon
Предполагается знание основ системы контроля версий Git. Если вы ещё не работали с Git, мы дадим ссылки на официальную русскоязычную документацию по необходимым командам.
Вам также потребуется аккаунт на GitHub. Регистрация бесплатная и требует указания лишь имени пользователя и электронной почты.
Вот процесс с высоты птичьего полёта.
Работа над задачей закончена!
Теперь рассмотрим каждый этап подробнее.
Форкаем проект
Поэтому мы форкаем проект — это создаст копию репозитория в вашем аккаунте. При этом у вас появится доступ на запись в вашу копию.
Через мгновение вы будете перенаправлены на страницу вашего форка.
Клонируем репозиторий
Затем выполняем команду в терминале ( или командной строке Windows):
Создаём ветку
Теперь заходим в наш склонированный репозиторий и создаём ветку:
Вторая команда создаст ветку и перейдёт на неё ( сделает checkout).
Делаем изменения
Эти изменения мы коммитим в нашу ветку. Как это сделать — ниже.
Если вы уже достаточно разбираетесь в Git, такие не-атомарные изменения потом нужно объединить в один коммит с помощью interactive rebase и squash.
В выводе есть все необходимые вам команды:
Формат сообщения о коммите таков:
В наших проектах нужно использовать Fix #123 или Close #123 на последней строке сообщения коммита.
Проверяем изменения
Создаём Pull Request
Чтобы создать Pull Request, зайдём на страницу вашего форка. Справа от выпадающего меню с выбором ветки есть кнопка « New pull request».
Вы попадаете в окно сравнения веток.
После нажатия кнопки появится окно ввода сообщения Pull Request.
Участвуем в Code Review
Если кто-то ведёт себя неадекватно — не медлите. Сначала сообщите об этом собеседнику и призовите его к благоразумию. Если не сработало — смело обращайтесь к рецензенту или к автору данного текста ( Панкову Михаилу — @mkpankov). Это можно сделать в нашем чате.
Пожелание относительно процесса рецензирования — постарайтесь не сильно затягивать с ответами на комментарии или изменением указанных вещей.
Поздравляем! Теперь вы полноправный участник проекта.
Завершение работы
А теперь можно удалить нашу ветку fix-protobaz локально:
Как сделать первый пул-реквест на 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
Пул-реквесты облегчают совместную работу разработчиков в Bitbucket. Они обеспечивают удобный веб-интерфейс для обсуждения предлагаемых изменений до их включения в официальный репозиторий проекта.
В упрощенном виде запросы pull — это механизм, с помощью которого разработчик уведомляет участников команды о том, что он подготовил некий функционал. Закончив работу над функциональной веткой, разработчик создает запрос pull с помощью аккаунта Bitbucket. Так все участники процесса узнают, что требуется проверить код и выполнить слияние с главной веткой ( main ).
Однако запрос pull — это не просто уведомление, а специальный форум для обсуждения предлагаемой функции. Если с изменениями возникли какие-либо проблемы, участники команды могут публиковать в запросе pull отзывы и даже изменять функцию с помощью дополнительных коммитов. Все эти действия отслеживается непосредственно внутри запроса pull.
По сравнению с другими моделями совместной работы это формальное решение для обмена коммитами обеспечивает гораздо более упорядоченный рабочий процесс. SVN и Git могут автоматически отправлять уведомления по электронной почте с помощью простого скрипта; однако когда дело доходит до обсуждения изменений, разработчикам обычно приходится вести диалог по электронной почте. Такой подход может внести путаницу, особенно если начинается обмен дополняющими коммитами. Запросы pull помещают все эти функции в удобный веб-интерфейс рядом с репозиториями Bitbucket.
Структура запроса pull
Создавая пул-реквест, вы всего лишь просите другого разработчика (например, человека, занимающегося поддержкой проекта) забрать ветку из вашего репозитория в его репозиторий. Поэтому для создания пул-реквеста необходимо указать 4 параметра: исходный репозиторий, исходную ветку, репозиторий назначения и ветку назначения.
Для многих параметров сервис Bitbucket определяет нужные значения по умолчанию. Однако в зависимости от того, как налажен процесс совместной работы команды, может потребоваться указать другие значения. На приведенной выше схеме показан запрос pull о слиянии функциональной ветки с официальной главной веткой, однако существует множество других способов использования запросов pull.
Порядок действий
Пул-реквесты можно применять в сочетании с процессами Feature Branch Workflow, Gitflow Workflow или Forking Workflow. При этом для использования пул-реквестов требуются две отдельные ветки или два отдельных репозитория. Поэтому пул-реквесты не будут работать при использовании процесса Centralized Workflow. Использование пул-реквестов в каждом из перечисленных процессов имеет свои нюансы, но общий подход описан ниже.
Разработчик создает функцию в отдельной ветке в своем локальном репозитории.
Разработчик отправляет эту ветку в публичный репозиторий Bitbucket командой push.
Разработчик создает запрос pull через Bitbucket.
Остальные участники команды проверяют код, обсуждают его и вносят изменения.
Человек, занимающийся поддержкой проекта, сливает функцию в официальный репозиторий и закрывает запрос pull.
Далее в этом разделе описывается, как запрос pull может использоваться в различных процессах совместной работы.
Использование запросов pull в рабочем процессе с функциональными ветками
В жизненном цикле функциональной ветки для организации совместной работы используется общий репозиторий Bitbucket, в котором разработчики создают новый функционал в изолированных ветках. Но вместо немедленного слияния кода с веткой main разработчики должны создать запрос pull, чтобы начать обсуждение функциональной ветки до ее включения в основную базу кода.
В процессе Feature Branch существует только один публичный репозиторий, поэтому исходный и целевой репозитории в запросе pull всегда будут совпадать. Обычно разработчик указывает свою функциональную ветку в качестве исходной, а ветку main — в качестве целевой ветки.
Получив запрос pull, человек, занимающийся поддержкой проекта, должен принять решение. Если функциональная ветка готова к использованию, можно выполнить слияние кода с веткой main и закрыть запрос pull. Но если в предлагаемых изменениях есть проблемы, можно оставить комментарии в запросе pull. Последующие коммиты будут отображаться рядом с соответствующими комментариями.
Кроме того, можно создать запрос pull для незавершенной функции. Например, если у разработчика возникают проблемы с реализацией определенного требования, он может создать запрос pull, содержащий его наработки. Другие разработчики могут оставить внутри этого запроса pull свои предложения или даже решить проблему, добавив дополнительные коммиты.
Использование запросов pull в рабочем процессе Gitflow
Рабочий процесс Gitflow похож на рабочий процесс с функциональными ветками, но устанавливает строгую модель ветвления, разработанную для релиза проекта. При добавлении запросов pull в рабочий процесс Gitflow разработчики получают удобное место для обсуждения ветки релиза или ветки сопровождения в ходе работы над ней.
Механизм запросов pull в рабочем процессе Gitflow аналогичен описанному выше: разработчик просто создает запрос pull, когда необходимо проверить функцию, релиз или ветку исправлений, а остальные участники команды получают уведомления через Bitbucket.
Использование запросов pull в рабочем процессе с форками
В процессе с использованием форков разработчик помещает завершенную функциональную ветку в собственный публичный репозиторий, а не в общий репозиторий. После этого разработчик создает пул-реквест, оповещая человека, занимающегося поддержкой проекта, о готовности кода к проверке.
Для этого рабочего процесса наличие уведомления в запросе pull особенно важно, иначе человек, занимающийся поддержкой проекта, не сможет узнать о том, что другой разработчик добавил коммиты в свой репозиторий Bitbucket.
Кроме того, пул-реквесты можно использовать для совместной работы с другими разработчиками за пределами официального репозитория проекта. Например, если разработчик работал над функциональной веткой вместе с коллегой, они могут создать пул-реквест, указав в качестве назначения репозиторий Bitbucket коллеги, а не официальный репозиторий проекта. Тогда они смогут указать в качестве исходной ветки и ветки назначения одну и ту же функциональную ветку.
Два разработчика могут обсуждать и разрабатывать функцию внутри запроса pull. По окончании разработки один из них создает новый запрос pull на слияние этой функции с официальной главной веткой. Такая гибкость делает запросы pull невероятно мощным инструментом совместной работы в рамках рабочего процесса с форками.
Пример
В приведенном ниже примере демонстрируется использование запросов pull в рабочем процессе с форками. Он одинаково применим как для разработчиков, работающих в маленьких командах, так и для независимых разработчиков, участвующих в проекте с открытым исходным кодом.
В данном примере Мэри — разработчик, а Джон — человек, занимающийся поддержкой проекта. У обоих есть собственные публичные репозитории Bitbucket, и в репозитории Джона находится официальный проект.
Мэри создает форк официального проекта
Чтобы начать работу над проектом, Мэри сначала должна создать форк репозитория Джона в Bitbucket. Для этого ей нужно войти в Bitbucket, перейти к репозиторию Джона и нажать кнопку Fork.
Указав имя и описание для репозитория, создаваемого с помощью форка, она получит копию серверной части проекта.
Мэри клонирует свой репозиторий Bitbucket
Затем Мэри должна клонировать репозиторий Bitbucket, который она только что создала с помощью форка. Так она получит собственную рабочую копию проекта на своей локальной машине. Она может сделать это с помощью следующей команды:
Мэри разрабатывает новый функционал
Прежде чем писать какой бы то ни было код, Мэри должна создать новую ветку для функции. Эту ветку она будет использовать в качестве исходной в запросе pull.
Мэри может выполнять сколько угодно коммитов во время работы над функциональной веткой. Если история создания функциональной ветки выглядит слишком запутанной, она может использовать интерактивную операцию rebase для удаления или склеивания ненужных коммитов. Такая очистка истории функциональной ветки в больших проектах помогает человеку, занимающемуся поддержкой проекта, быстрее понять, что включено в пул-реквест.
Мэри помещает функциональную ветку в свой репозиторий Bitbucket
Закончив свою задачу, Мэри помещает функциональную ветку в собственный репозиторий Bitbucket (не в официальный репозиторий проекта) с помощью простой команды git push :
Так изменения Мэри будут доступны человеку, занимающемуся поддержкой проекта (или любым другим участникам, которым может понадобиться доступ к этим изменениям).
Мэри создает запрос pull
После добавления своей функциональной ветки в Bitbucket Мэри из своего аккаунта Bitbucket может создать пул-реквест, перейдя в свой репозиторий, созданный с помощью форка, и нажав на кнопку Pull request в верхнем правом углу. Отобразится форма, в которой репозиторий Мэри автоматически будет указан в качестве исходного. Мэри останется указать исходную ветку, а также репозиторий и ветку назначения.
После создания запроса pull Джону будет отправлено уведомление через Bitbucket и (опционально) по электронной почте.
Джон просматривает запрос pull
Джон может увидеть все созданные другими разработчиками пул-реквесты, перейдя на вкладку Pull request в своем репозитории Bitbucket. Нажав на пул-реквест Мэри, он увидит описание пул-реквеста, историю коммитов функциональной ветки и все изменения в пул-реквесте.
Но для примера представим, что Джон нашел небольшой баг в коде Мэри и хочет, чтобы он был исправлен перед слиянием. Джон может либо опубликовать комментарий к запросу pull в целом, либо выбрать определенный коммит в истории функциональной ветки и прокомментировать его.
Мэри добавляет дополняющий коммит
Если у Мэри есть какие-либо вопросы по поводу отзыва Джона, она может ответить внутри запроса pull, используя его как форум для обсуждения функции.
Для исправления ошибки Мэри добавляет другой коммит в свою функциональную ветку и помещает этот коммит в свой репозиторий Bitbucket, как и в первый раз. Коммит автоматически добавится в исходный запрос pull, и Джон сможет снова просмотреть изменения прямо рядом с его исходным комментарием.
Джон принимает запрос pull
Куда можно перейти отсюда
Теперь у вас есть все необходимые инструменты, чтобы начать использование пул-реквестов в текущем рабочем процессе. Помните, что пул-реквесты не заменяют процессы совместной работы в Git, а лишь дополняют их, облегчая взаимодействие всех членов команды.
Готовы попробовать создать запрос pull?
Ознакомьтесь с этим интерактивным обучающим руководством.