Pull requests что это
Как сделать pull request
Pull Request — запрос на включение. На включение написанного вами кода в чужой репозиторий.
С чего начать?
А для начала этот самый репозиторий нужно форкнуть (fork — вилка, ответвление). Разберём это нехитрое действо на примере веб-сервиса для хостинга IT-проектов, название которому GitHub. Разумеется, кроме GitHub есть и другие: BitBucket, например. Выбирать по вкусу.
Для успешного проведения нижеизложенных операций у вас (что естественно) должен быть установлен git
В консоли в зависимости от входных данных набираем нечто подобное:
Отлично. Уже можно вносить свои изменения в код проекта.
Тот репозиторий, что теперь лежит на вашем жёстком диске, независим от основного. В нём отслеживаются только ваши наработки. Но как следить за изменениями, происходящими в первоисточнике, откуда вы « стянули » репозиторий? Добавить удаленный репозиторий в отслеживаемые. Например, так:
Давайте посмотрим как сливать изменения из оригинального репозитория к себе в случае, если разработка в нём ушла вперёд пока вы сосредоточенно писали коммиты:
Если репозиторий огромен, а забирать его весь не хочется, клонируем только нужную ветку:
Что такое ветки?
Чаще всего ветки (branch — ответвление, ветвь, филиал) бывают тематическими. Например, при общей разработке, когда у всех участников есть право записи в репозиторий. В этом случае ветки используются для отделения изменений, сделанных одним из разработчиков, от общего репозитория. Ветки могут пригодиться и в случае с созданием pull-request’а.
Создание ветки происходит довольно просто. Находясь в каталоге с проектом, наберите следующие команды:
Новые ветки создаются не только из master, берите любую!
Находясь в только что созданной ветке, вы можете приступить к работе. Вносите в код свои изменения, а когда закончите просто переключитесь обратно к своей основной ветке. Вы можете отправить pull request, выбрав ветку new_branch или же прежде слить изменения из неё в основную ветку разработки. Рассмотрим это подробнее:
Если нужно отправить в свой удалённый репозиторий вновь созданную ветку (не сливать её с master), делаем следующее:
Не торопитесь сливать изменения. Если что-то не заладилось, созданную ветку можно удалить:
Удалить все локальные ветки, которые были смержены (то есть код которых теперь есть) в ветках develop или master:
Отправляем изменения
Добрались таки до ответа на поставленный вопрос: что такое pull request, зачем оно нужно и как его достичь. Как предложить владельцу репозитория свои изменения?
Для этого зайдите в свой аккаунт, выбирайте репозиторий владельца и ищите небольшую зелёную кнопку (на момент написания поста она была таковой, если даже что-то изменится, думаю, найти её будет несложно).
А дальше. ждать. Пока придёт владелец оригинального репозитория и примет/отклонит ваши изменения.
Ну вот, мы его достигли. Просветления то есть 🙂
Как отменить изменения
Когда нужно вернуть более старое состояние уже проиндексированных файлов и забыть о них совсем (помните, что упомянутая здесь операция отменит всю вашу работу до определённого коммита!):
Cмотрим на какой коммит откатиться. В примере откатываемся назад на 1 коммит. Для изменения состояния в этой же ветке удалённого репозитория тоже придётся использовать грубую силу — флаг force :
Или посмотреть все изменения, которые происходили с отдельным файлом:
А подробнее?
Итогов подводить не стану. Для заинтересованных лиц ссылочка на неофициальную документацию: The Git Community Book
Pull requests что это
Создание и сопровождение Pull Request
При работе над проектом будут создаваться feature-ветки в git, которые потом необходимо вливать в основную ветку (продуктовую или develop, в зависимости от деталей workflow, который используется на проекте). Так или иначе, очень важно понимать, что просто создать Pull Request — это еще не завершение вашей задачи.
Pull Request имеет одно очень неприятное свойство — терять актуальность. Код в target ветке начинает конфликтовать с кодом в вашей feature-ветке, Pull Request может обрасти рядом комментариев и вопросов, которые препятствуют мерджу вашего Pull Request. В общем, создание и сопровождение Pull Request — это такая же задача, как и разработка фичи.
Как оформить Pull Request
Прежде всего ему нужно дать осмысленное название, которое коротко отразит вносимые вами изменения в проект: «добавлен вывод последних новостей», «исправлена ошибка открытия меню» и так далее. Но самое важное — Pull Request должен иметь определенные маркеры в заголовке, отражающие его текущее состояние. Обычно такими маркерами выступают [WIP] (Work In Progress) и [RFC] (Ready For Comment).
Эти маркеры нужны прежде всего для ревьюеров. Если ревьюер увидит Pull Request с маркером [RFC], то он сможет приступить к code review, когда у него будет на это время. Если же в заголовке вашего Pull Request будет стоять маркер [WIP], то будет сразу понятно, что этот Pull Request проверять еще рано.
Кроме того, эти маркеры могут меняться, например, Pull Request уже имел маркер [RFC], но в результате code review были выявлены некоторые проблемы, которые следует устранить. В этом случае необходимо изменить [RFC] на [WIP]. Такой подход поможет сэкономить время ревьюеров, так как они не будут заглядывать в Pull Requests, которые в данный момент не готовы к review.
В итоге, название вашего Pull Request должно быть приблизительно таким:
[RFC] [issue-id] Добавлена возможность оформлять заказ одним кликом
или, если в вашем Repository Hub (Github) нет линков на issues, в названиях Pull Requests:
[WIP] Исправлена ошибка при клике по ссылке на новость
В Github для маркировки Pull Request стоит использовать лейблы вместо текста в заголовках. Лейблы лучше видны, плюс они могут иметь цветовую индикацию, позволяющую определить статус Pull Request еще под цвету маркера, а также настроить фильтры.
Описание Pull Request должно быть максимально информативным. Не нужно писать в нем все, что сделано в вашей feature-ветке, обычно это и так описано в задаче, породившей вашу feature-ветку. В описании следует писать почему вы сделали так, как сделали. Можно еще добавить пару слов о том, на что ревьюерам стоит обратить особое внимание.
Помните, что описание Pull Request в идеале должно ответить на все возможные вопросы.
Но вполне может быть и так, что описание для вашего Pull Request не требуется и все понятно из заголовка. Здесь, к сожалению, нет четкой грани, когда стоит писать описание, а когда его можно опустить, но, если вы чувствуете, что описания может быть недостаточно или оно не отвечает на все вопросы по реализации задачи/фиксу бага, то нужно постараться заранее ответить на них в описании.
Сопровождение Pull Request
Важно понимать, что чем раньше вы ответите на вопрос в вашем Pull Request или разрешите конфликт в коде, тем быстрее этот Pull Request вмержат в target-ветку.
Но бывают ситуации, когда конфликты появляются чаще, чем вы успеваете их разрешать. В этом случае, лучше всего поставить маркер [WIP] и дождаться стабилизации участка кода, который начал активно конфликтовать с вашим Pull Request. Такое бывает, когда происходит merge нескольких похожих Pull Requests.
Очень важно понимать, что целью code review является выявление слабых или некорректных архитектурных решений, а не выполнение работы линтера. Все, что можно автоматизировать, нужно автоматизировать.
В идеале, Pull Request должен автоматически проверяться линтерами, должны прогоняться автотесты, после чего уже ревьюеру следует тратить время на code review. К сожалению, такая автоматизация может быть не на всех проектах, поэтому автору Pull Request в такой ситуации перед проставлением маркера [RFC] в заголовок Pull Request нужно прогнать линтеры и автотесты, чтобы убедиться, что все в порядке.
Желательно, чтобы code review проводили несколько человек (как минимум двое), но не стоит назначать ревьюерами всю команду. Это не очень сильно увеличит эффективность code review, но значительно удорожит этот процесс. Но бывают и исключения, когда все члены команды должны принять участие в code review. Обычно это связано с радикальными изменениями в проекте, либо в его инфраструктуре.
После того, как вы создали Pull Request, успешно прошли стадию code review, исправили все замечания и ответили на все вопросы, ваш Pull Request наверняка получит approve от всех ревьюеров, а уже после этого последует его merge в target-ветку. Поздравляю! Работа над этой задачей завершена, если конечно она не вернется к вам после тестирования QA-инженерами.
Что такое пул-реквесты и зачем они нужны?
Перевод статьи «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 локально:
Практическое занятие «Процесс Pull request на GitHub»
На предыдущем занятии Используем клиент GitHub для десктопа, мы использовали Github Desktop для управления рабочим процессом коммитов, ветвления и слияния. На этом занятии мы будем выполнять аналогичные действия, но с использованием браузерного интерфейса, который предоставляет Github, вместо использования терминала или Github Desktop.
Понимание процесса Pull request является важным для анализа изменений в опен-сорс проекте с несколькими участниками. Использование интерфейса GitHub также удобно, если рецензенты не знакомы с терминалом или Github Desktop.
Создание изменение в отдельной ветке
По умолчанию в новом репозитории есть одна ветка с именем «Master». Обычно, когда при внесении изменений или просмотра / редактировании, создается новая ветка и вносятся все изменения в ветку. Затем, по окончании, владелец репо объединяет изменения из новой ветки в «Master» через «pull request».
Для создания изменений в отдельной ветке:
При создании новой ветки, содержимое из главной (или любой другой ветки, которая сейчас просматривается) копируется в новую ветку. Процесс похож на «Сохранить как» с существующим документом.
Рецензенты могут продолжать вносить изменения таким образом, пока не закончат просмотр всей документации. Все изменения делаются в этой новой ветке, а не в мастере.
Создание Pull request
Для создания Pull request:
Когда мы сравниваем ветку с мастером, мы увидим список всех изменений. Мы можем просмотреть изменения в двух режимах просмотра: Unified или Split (это вкладки, показанные справа от содержимого). Unified показывает правки вместе в одной области содержимого, тогда как split показывает два файла рядом.
Владелец репозитория увидит pull request и сможет принять меры для его объединения.
Процесс Pull request
Теперь посмотрим на процесс со стороны владельцем проекта, который получил новый Pull request. Владельцу нужно обработать Pull request и объединить ветку sme-review с “Master”.
Также стоит обратить внимание, что если запрос на извлечение выполняется для более старой версии мастера, где исходное содержимое мастера больше не существует или перемещено в другое место, процесс слияния будет более трудным для выполнения.
Ветка sme-review объединяется с мастером. Теперь “Master” и ветка sme-review совпадают (ветки “смержены”).
Если посмотреть на список веток, то после удаления ветка sme-review больше не отображается.
Добавление участников в проект
Иногда необходимо добавлять соавторов в проект Github, чтобы они могли вносить изменения в ветку. Если другие участники проекта, не являясь соавторами, захотят внести изменения, они получат сообщение об ошибке. (Inviting collaborators to a personal repository)
Человек без прав на запись, может “форкнуть” (скопировать) репо, а не вносить изменения в ветку в том же проекте. Однако копирование проекта клонирует весь репозиторий, а не создает ветку в том же репозитории. Форк (копия) будет существовать в учетной записи пользователя GitHub. Можно объединить форкнутый репозиторий (это типичная модель для опен-сорс проектов со многими внешними участниками), но этот сценарий, вероятно, менее распространен для технических писателей, работающих с разработчиками в тех же проектах.
Для добавления соавторов в проект: