Как настроить pull request

Выполнение запроса 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.

Слияние функциональных веток обычно выполняют с веткой разработки develop , а слияние веток релизов и исправлений выполняют и с веткой develop , и с веткой main . Запросы pull можно использовать в качестве инструмента формального управления всеми этими слияниями.

Использование запросов pull в рабочем процессе с форками

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

Для этого рабочего процесса наличие уведомления в запросе pull особенно важно, иначе человек, занимающийся поддержкой проекта, не сможет узнать о том, что другой разработчик добавил коммиты в свой репозиторий Bitbucket.

Поскольку у каждого разработчика есть свой публичный репозиторий, исходный и целевой репозитории в запросе pull будут отличаться. Исходным будет публичный репозиторий разработчика, а исходной веткой — та, что содержит предлагаемые изменения. Если разработчик предлагает слить функциональную ветку с основной базой кода, целевым репозиторием будет официальный репозиторий проекта, а целевой веткой — главная ветка main .

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

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

Пример

В приведенном ниже примере демонстрируется использование запросов pull в рабочем процессе с форками. Он одинаково применим как для разработчиков, работающих в маленьких командах, так и для независимых разработчиков, участвующих в проекте с открытым исходным кодом.

В данном примере Мэри — разработчик, а Джон — человек, занимающийся поддержкой проекта. У обоих есть собственные публичные репозитории Bitbucket, и в репозитории Джона находится официальный проект.

Мэри создает форк официального проекта

Чтобы начать работу над проектом, Мэри сначала должна создать форк репозитория Джона в Bitbucket. Для этого ей нужно войти в Bitbucket, перейти к репозиторию Джона и нажать кнопку Fork.

Указав имя и описание для репозитория, создаваемого с помощью форка, она получит копию серверной части проекта.

Мэри клонирует свой репозиторий Bitbucket

Затем Мэри должна клонировать репозиторий Bitbucket, который она только что создала с помощью форка. Так она получит собственную рабочую копию проекта на своей локальной машине. Она может сделать это с помощью следующей команды:

Помните, что команда git clone автоматически создает удаленный репозиторий origin , который указывает на репозиторий Мэри, созданный с помощью форка.

Мэри разрабатывает новый функционал

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

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

Мэри помещает функциональную ветку в свой репозиторий Bitbucket

Закончив свою задачу, Мэри помещает функциональную ветку в собственный репозиторий Bitbucket (не в официальный репозиторий проекта) с помощью простой команды git push :

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

Мэри создает запрос pull

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

Мэри хочет выполнить слияние функциональной ветки с основной базой кода. При этом исходной веткой будет ее функциональная ветка, целевым репозиторием — публичный репозиторий Джона, а целевой веткой — ветка main . Мэри потребуется ввести заголовок и описание запроса pull. Если кто-либо еще кроме Джона должен одобрить код Мэри, она может указать нужных людей в поле Reviewers (Проверяющие).

После создания запроса pull Джону будет отправлено уведомление через Bitbucket и (опционально) по электронной почте.

Джон просматривает запрос pull

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

Если Джон считает функционал готовым к слиянию с проектом, ему достаточно нажать кнопку Merge (Слияние), чтобы одобрить запрос pull и выполнить слияние функционала Мэри со своей веткой main .

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

Мэри добавляет дополняющий коммит

Если у Мэри есть какие-либо вопросы по поводу отзыва Джона, она может ответить внутри запроса pull, используя его как форум для обсуждения функции.

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

Джон принимает запрос pull

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

Куда можно перейти отсюда

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

Готовы попробовать создать запрос pull?

Ознакомьтесь с этим интерактивным обучающим руководством.

Источник

Как создать идеальный Pull Request

С ростом компании меняются люди и проекты. Не так давно в блоге GitHub появилась интересная статья, в которой автор рассказывает, как делать, а как лучше не делать Pull Request’ы. Перевод, традиционно, спрятан под катом.

Правильный подход к написанию Pull Request

• Четко определите назначение этого pull request. Например:
• Будет хорошо, если вы включите краткое описание зачем вообще делалась эта работа (включая релевантные ссылки). Не стоит рассчитывать, что читающий реквест разработчик будет знаком со всей историей.
• Имейте в виду, что этот реквест потенциально может читать любой сотрудник компании. Возможно, через год.
• Явно пишите, какую реакцию вы ожидаете в ответ на этот реквест. Хотите ли вы от читающего что-то, кроме merge? Просто посмотреть на код, оценить техническую реализацию, критика дизайна, ревью текста и так далее.
• Явно указывайте когда вы ожидаете ответ. Если реквест в процессе работы, то общепринятой практикой является добавление префикса “[WIP]” (work in progress) к его описанию. Это позволит читающим отгрузить вам ранние комментарии, при этом понимая, что они смотрят не на законченную работу.
• @Упоминайте тех, кого вы хотели бы видеть в обсуждении реквеста. И упоминайте почему, для этого есть специальный синтаксис:
• @Упоминать можно не только разработчиков, но и команды. То же относится к причинам, что и зачем вы хотите с ними обсудить:

Реакция на чужой pull request

• Постарайтесь изучить контекст, в котором случился этот Pull Request: связанные задачи, обсуждения, история вопроса. Если все это есть, конечно.
• Если Pull Request вызывает у вас инстинктивную негативную реакцию – возьмите тайм-аут в несколько минут и еще раз все внимательно осмотрите. Возможно, автор не идиот у вас просто случилась ошибка коммуникации. Такое встречается на удивление часто.
• Спрашивайте, а не предлагайте. Простой и эффективный психологический трюк для облегчения коммуникаций. Фраза «Что ты думаешь насчет использования…?» гораздо меньше провоцирует на конфликт, нежели «убей себя не делай так».
• Старайтесь объяснять, почему необходимо поменять код (противоречит стилю кодирования? Персональное предпочтение?)
• Предлагайте пути упростить и улучшить код. Это воспринимается намного лучше, чем просто критика «все плохо».
• Кстати, о критике. Старайтесь избегать оценок вроде «глупо» по отношению к чужой работе. Очень хорошо помогает наладить коммуникации.
• Скромнее надо быть. Для дела надо – «не уверен, но давай попробуем…» помогает найти общий язык намного лучше, чем «я 20 лет этим занимаюсь. Делай вот так и не спрашивай почему».
• Избегайте гипербол («НИКОГДА не делай…»). Все их воспринимают совсем по-разному.
• Ставьте своей целью развитие профессиональных качеств, знаний компании и увеличения качества продукта. Звучит заезжено? Да, но обычно ставят цель потешить свое самолюбие за счет критики.
• Учитывайте «negative bias» онлайн коммуникаций (для нейтрального содержания мы всегда предполагаем негативный тон). Чтобы не расставлять по тексту смайлики, можно воспользоваться «позитивным» языком.
• Если «позитивный» язык использовать трудно (журналисты много лет этому учатся не просто так), то на помощь приходят… эмодзи, как это ни странно. Сравните: «:sparkles: :sparkles: Looks good :+1: :sparkles: :sparkles:” и “Looks good”.

Чужая реакция на ваш pull request

• По возможности начинайте ответ со слов благодарности, особенно если реакция на ваш реквест противоречива.
• Если что-то не понятно – не стесняйтесь задавать уточняющие вопросы («I don’t understand, can you clarify?»). Это намного эффективнее, чем пытаться самому «придумать» что имел в виду другой разработчик.
• Сами старайтесь предоставлять всю уточняющую информацию и рассказывать о причинах тех или иных решений в коде.
• Старайтесь отвечать на каждый комментарий.
• Линкуйте коммиты и другие пулл реквесты («Good call! Done in 1682851”)
• Если обсуждение начало перерастать в дебаты, остановитесь и спросите себя, имеет ли смысл продолжать диалог в письменной форме. Практика показывает, что в большинстве случаев гораздо удобнее обсудить все в скайпе или другом голосовом чате, а затем дописать в виде текста только краткую выжимку и результат обсуждения.

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

Источник