Выполнение пул-реквеста

Making a Pull Request

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

Git Workflows: Pull Request in Bitbucket

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

But, the pull request is more than just a notification—it’s a dedicated forum for discussing the proposed feature. If there are any problems with the changes, teammates can post feedback in the pull request and even tweak the feature by pushing follow-up commits. All of this activity is tracked directly inside of the pull request.

Git Workflows: Activity inside a pull request

Compared to other collaboration models, this formal solution for sharing commits makes for a much more streamlined workflow. SVN and Git can both automatically send notification emails with a simple script; however, when it comes to discussing changes, developers typically have to rely on email threads. This can become haphazard, especially when follow-up commits are involved. Pull requests put all of this functionality into a friendly web interface right next to your Bitbucket repositories.

Anatomy of a Pull Request

Создавая пул-реквест, вы всего лишь просите другого разработчика (например, человека, занимающегося поддержкой проекта) забрать ветку из вашего репозитория в его репозиторий. Поэтому для создания пул-реквеста необходимо указать 4 параметра: исходный репозиторий, исходную ветку, репозиторий назначения и ветку назначения.

Git Workflows: Pull Requests

Many of these values will be set to a sensible default by Bitbucket. However, depending on your collaboration workflow, your team may need to specify different values. The above diagram shows a pull request that asks to merge a feature branch into the official master branch, but there are many other ways to use pull requests.

How it works

Пул-реквесты можно применять в сочетании с процессами Feature Branch Workflow, Gitflow Workflow или Forking Workflow. При этом для использования пул-реквестов требуются две отдельные ветки или два отдельных репозитория. Поэтому пул-реквесты не будут работать при использовании процесса Centralized Workflow. Использование пул-реквестов в каждом из перечисленных процессов имеет свои нюансы, но общий подход описан ниже.

  1. A developer creates the feature in a dedicated branch in their local repo.

  2. The developer pushes the branch to a public Bitbucket repository.

  3. The developer files a pull request via Bitbucket.

  4. The rest of the team reviews the code, discusses it, and alters it.

  5. The project maintainer merges the feature into the official repository and closes the pull request.

The rest of this section describes how pull requests can be leveraged against different collaboration workflows.

Feature Branch Workflow With Pull Requests

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

Pull Request: Feature Branch workflow

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

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

It’s also possible to file a pull request for a feature that is incomplete. For example, if a developer is having trouble implementing a particular requirement, they can file a pull request containing their work-in-progress. Other developers can then provide suggestions inside of the pull request, or even fix the problem themselves with additional commits.

Gitflow Workflow With Pull Requests

The Gitflow Workflow is similar to the Feature Branch Workflow, but defines a strict branching model designed around the project release. Adding pull requests to the Gitflow Workflow gives developers a convenient place to talk about a release branch or a maintenance branch while they’re working on it.

Pull Requests: Gitflow Workflow Pull Requests: Gitflow Workflow 2

The mechanics of pull requests in the Gitflow Workflow are the exact same as the previous section: a developer simply files a pull request when a feature, release, or hotfix branch needs to be reviewed, and the rest of the team will be notified via Bitbucket.

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

Forking Workflow With Pull Requests

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

The notification aspect of pull requests is particularly useful in this workflow because the project maintainer has no way of knowing when another developer has added commits to their Bitbucket repository.

Pull Requests: Forking workflow

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

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

Pull Requests: Forking workflow

The two developers could discuss and develop the feature inside of the pull request. When they’re done, one of them would file another pull request asking to merge the feature into the official master branch. This kind of flexibility makes pull requests very powerful collaboration tool in the Forking workflow.

Example

The example below demonstrates how pull requests can be used in the Forking Workflow. It is equally applicable to developers working in small teams and to a third-party developer contributing to an open source project.

In the example, Mary is a developer, and John is the project maintainer. Both of them have their own public Bitbucket repositories, and John’s contains the official project.

Mary forks the official project

Pull Requests: Fork the project

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

Pull Request: Fork in Bitbucket

After filling out the name and description for the forked repository, she will have a server-side copy of the project.

Mary clones her Bitbucket repository

Pull Request: Clone the Bitbucket repo

Next, Mary needs to clone the Bitbucket repository that she just forked. This will give her a working copy of the project on her local machine. She can do this by running the following command:

git clone https://user@bitbucket.org/user/repo.git

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

Mary develops a new feature

Pull Requests: develop a new feature

Before she starts writing any code, Mary needs to create a new branch for the feature. This branch is what she will use as the source branch of the pull request.

git checkout -b some-feature
# Измените код
git commit -a -m "Добавление нового функционала в черновом варианте"

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

Mary pushes the feature to her Bitbucket repository

Pull Requests: Push feature to Bitbucket repository

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

git push origin some-branch

This makes her changes available to the project maintainer (or any collaborators who might need access to them).

Mary creates the pull request

Pull Request: Create Pull Request

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

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

Pull Request: Bitbucket

After she creates the pull request, a notification will be sent to John via his Bitbucket feed and (optionally) via email.

John reviews the pull request

Pull Request: Bitbucket pull requests

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

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

But, for this example, let’s say John found a small bug in Mary’s code, and needs her to fix it before merging it in. He can either post a comment to the pull request as a whole, or he can select a specific commit in the feature’s history to comment on.

Pull Request: Comment

Mary adds a follow-up commit

If Mary has any questions about the feedback, she can respond inside of the pull request, treating it as a discussion forum for her feature.

To correct the error, Mary adds another commit to her feature branch and pushes it to her Bitbucket repository, just like she did the first time around. This commit is automatically added to the original pull request, and John can review the changes again, right next to his original comment.

John accepts the pull request

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

Where to go from here

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

Ready to try pull requests?

Try this interactive tutorial.

Начните прямо сейчас