创建拉取请求

Making a Pull Request

拉取请求是一种功能,可让开发人员使用 Bitbucket 更轻松地进行协作。它们提供用户友好的网络界面,用于讨论建议的变更,然后将变更集成到正式项目中。

Git Workflows: Pull Request in Bitbucket

简单而言,拉取请求是一种通知机制,让开发人员通知团队成员自己已完成某项功能。当开发人员的功能分支准备就绪后,可以通过自己的 Bitbucket 账户提出拉取请求。这样,所有相关人员都会知道需要审查代码并合并到 master 分支中。

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.

工作原理

拉取请求可以与功能分支工作流Git 流工作流创建新拷贝工作流一起使用。但是,拉取请求需要两个不同的分支或两个不同的代码库,因此无法与集中式工作流一起使用。这些工作流对拉取请求的使用略有不同,但一般过程如下:

  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 代码库来管理协作,开发人员在隔离的分支中创建功能。但是,开发人员不是立即将它们合并到 master 中,而应该打开一个拉取请求,围绕该功能展开讨论,然后再集成到主代码基准中。

Pull Request: Feature Branch workflow

功能分支工作流中只有一个公有代码库,因此拉取请求的目标代码库和源代码库总是一致的。通常情况下,开发人员将其功能分支指定为源分支,将 master 分支指定为目标分支。

收到拉取请求后,项目维护者必须决定该如何做。如果功能准备就绪,他们只需将其合并到 master 中并关闭拉取请求。但是,如果建议的变更有问题,他们可以在拉取请求中发布反馈。后续的提交将显示在相关评论旁边。

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.

功能一般合并到 develop 分支中,而发布和热补丁分支则合并到 developmaster 中。可以使用拉取请求来正式管理所有这些合并。

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

由于每个开发人员都有自己的公有代码库,拉取请求的源代码库将不同于目标代码库。源代码库是开发人员的公有代码库,而源分支是包含建议的变更的源分支。如果开发人员尝试将该功能合并到主代码基准中,那么目标代码库是正式项目,目标分支是 master

拉取请求还可用来与正式项目之外的其他开发人员协作。例如,如果开发人员正与队友合作处理功能,那么他们可以提出拉取请求,使用队友的 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.

示例

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

要开始在项目中工作,Mary 首先需要对 John 的 Bitbucket 代码库执行拷贝 (fork) 操作。她可以登录 Bitbucket,导航到 John 的代码库,然后单击 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 会自动创建一个指回 Mary 拷贝的代码库的 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
# Edit some code
git commit -a -m "Add first draft of some feature"

Mary 可以使用尽可能多的所需提交来创建该功能。而且,如果该功能的历史记录比她想的更混乱,她可以使用交互式变基来删除或压缩不必要的提交。对于较大的项目,清理功能的历史记录可让项目维护人员更轻松地查看拉取请求中发生的情况。

Mary pushes the feature to her Bitbucket repository

Pull Requests: Push feature to Bitbucket repository

在她的功能完成后,Mary 使用简单的 git push 将功能分支推送到自己的 Bitbucket 代码库(而不是正式代码库)中:

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 有她的功能分支后,Mary 就可以通过 Bitbucket 账户创建拉取请求,方法是导航到已拷贝的代码库,然后单击右上角的 Pull request 按钮。生成的表单会自动将 Mary 的代码库设置为源代码库,并要求她指定源分支、目标代码库和目标分支。

Mary 想将她的功能合并到主代码基准中,所以源分支是她的功能分支,目标代码库是 John 的公有代码库,目标分支是 master。她还需要提供拉取请求的标题和描述。如果除 John 之外还需要其他人批准代码,那么她可以在 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

John 可以通过点击他自己的 Bitbucket 代码库中的 Pull request 选项卡来访问大家提出的所有拉取请求。点击 Mary 的拉取请求将向他显示拉取请求的描述、功能的提交历史记录以及它包含的所有变更的不同之处。

如果他认为可以将该功能合并到项目中,那么他需要做的就是点击 Merge 按钮来批准拉取请求,并将 Mary 的功能合并到他的 master 分支中。

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

最后,John 接受这些变更,将功能分支合并到主分支中,并关闭拉取请求。该功能现在被集成到项目中,任何处理该功能的其他开发人员都可以使用标准的 git pull 命令将其拉入自己的本地代码库中。

下一步

现在您已经拥有了所需的全部工具,可以将拉取请求集成到现有的工作流中。请注意,拉取请求并不是基于 Git 的协作工作流的替代品,而是对后者的补充,让所有团队成员更容易开展协作。

Ready to try pull requests?

Try this interactive tutorial.

立即开始