GitHub帮助-使用Pull Request

作者 happyWang 日期 2014-10-16 浏览量
GitHub帮助-使用Pull Request

本文是翻译的https://help.github.com/articles/using-pull-requests/ 。旨在帮助大家了解 GitHub 上面如何给别人的仓库提交变更,英文好的同学可以查看上述网址,获取最新的内容

Pull Request 可以让你通知别人,你已经推送了一个修改到 GitHub 的版本库。在 pull request 被发送之后,感兴趣的成员可以 review 这些代码变动,讨论可能需要的修改,甚至在必要的时候在这之后 push 一些 commits 本指南详细描述了从发送一个 pull request(假设的),使用各种代码审查工具和管理工具,到最后完成变更的过程。

协同开发模式的快速笔记

在 GitHub 上面有两种流行的协同开发模式:

Fork & Pull

Fork & Pull 模式让任何人都可以 fork(复制的意思)一个已经存在的版本库并且提交变更到他们自己 fork 出来的版本库上,而不需要获得源版本库的访问权限。变更必须通过项目维护者才能放入源版本库。这种模式降低了给新贡献者带来的麻烦,在开源项目非常流行,因为它使人们能够独立工作而不需要前期的协调。

共享版本库模式

共享版本库模式在小团队和组织合作的私人项目中更为普遍。每个人都有 push 到单一共享版本库或者用来隔离变更的顶级分支的权限。 Pull requests 在 Fork & Pull 模式 中更加有用,因为它提供了一种方法去提醒项目维护者,在他的 fork 里面有变更. 但是,在共享版本库模式中,他们同样有用,当人们启动代码审查或者在合并到主分支之前讨论所有变更的时候

开始之前

本指南假设您有一个GitHub 的帐户 ,你已经 Fork 了一个的现有版本,并 push 了您的更改。想要获得关于 Fork 和推送变更的帮助,请参阅文章——Forking a Repo

启动 Pull Request

在下面的例子中,codercat 在 Fork 自 Octocat 的 Spoon-Knife 版本库中完成了一些工作,在他的 Fork 中 push 了一个 commit,并希望有人来审查和合并。 进入到你希望别人 Pull 变更的版本库中,点击 Pull Request 按钮。

  1. 切换到您的分支 分支选择下拉
  2. 点击 Compare & review 按钮 Pull Request 按钮

Pull request 可以基于任何分支或者 commit 发送,但是推荐是从一个顶级分支。这样,在必要的时候,一些跟随的 commit 可以被 push,去更新这个 Pull Request。

审查要提交的 Pull Request

开始审查之后,你将会进入一个审查页面,在这里你可以概览到所有在你的分支和源版本库的 master 分支之间的变动。你可以审查在所有 commit 中的注释,明白哪些文件发生了变动,看到所有在你的分支中的贡献者。 Pull Request 复审页

改变分支范围和目标版本库

默认情况下,Pull Request 被认为是基于父版本库的默认分支 。在这种情况下, hubot/Spoon-Knife 是 contoctocat/Spoon-Knife 中 Fork 出来的。所以这次的 Pull Request 被假定为基于 octocat/Spoon-Knife 版本库的 master 分支。 在绝大多数情况下,默认值将是正确的,但是,如果有任何信息不正确,您可以从下拉列表中更改父版本库和分支。点击顶部的 Edit 按钮,可以让你换你的头和底座,以及建立各种参考点之间的差别。这里引用可以包括:

  • 添加了 tag 的 release
  • commit 的 SHA 值
  • 分支名称
  • Git 的历史标志(如 HEAD^1 )
  • 有效的时间引用(如 master@{1day} )

欲了解更多信息,请查看our help article on setting up comparisons

Pull Request 选择比较的分支

理解分支范围的最简单的方法是这样的:

基础分支( base branch )是你认为变更应该应用的分支,而头部分支( head branch )是你想被人应用的分支 。

改变基础版本库会导致 Pull Request 发生时候的通知名单发送变动。所有对基础版本库有 push 权限的人都会在新的 Pull Request 产生的时候收到邮件,并且在他们下次登录的时候能够在他们的仪表盘查看该 Pull Request。

当您更改分支范围内的任何信息,commit 和文件改动的预览区域将更新以显示新的范围。

发送 Pull Request

当你准备好提交您的 Pull Request,点击Create pull request按钮: Pull Request 提交

你会被带到一个讨论页面,在这里你可以输入一个标题和说明(可选)。你仍然可以看到,当 Pull Request 发送时哪些 commit 将包括在内。

当你你输入好标题和描述,针对 commit 范围做了必要的自定义,审查了要发送的 commit 和修改的文件,按Send pull request按钮。

Pull Request 发送按钮

Pull Request 会被立即发送。你会被带往一个 Pull Request 讨论和审核的主页。

在你的 Pull Request 发送之后,任何 push 到你的分支的 commit 会被自动更新上去。如果您需要更多的改变,这尤其有用。

管理 Pull Request

所有经由你发送或者审核的 Pull Request 都可以通过仪表盘的 pull request 查看。给自定版本库的 Pull Request,对于所有能够访问对应 Pull Request 页面的人来说,也是可见的。

已有的Pull Request 列表

Pull Request 仪表板和版本库的 Pull Request 列表支持多种筛选和排序控件。用它们来把列表缩小到你感兴趣的 Pull Request

审查建议的更改

当您收到一个 Pull Request,要做的第一件事就是审查这些建议的更改。Pull Request 被紧密地与底层的 git 仓库集成,所以你可以看到如果 Request 被接受,哪些 commit 会被合并:

commit 审核页

您还可以了解所有提交,查看所有文件更改的累计差异。

差异审核页

讨论 Pull Request

审查了基本说明,commit,和累积差异后,负责应用更改的人可能有问题或意见。也许是编码风格不匹配项目的指引,或变更缺少单元测试,或者也许一切看起来不错,所有事情都准备就绪。设计这种讨论会面,旨在鼓励和关注这种类型的讨论。

Pull Request 讨论

这种讨论会面从 Pull Request 的原始标题和描述开始,然后从那里按时间顺序显示额外的活动。任何以下类型的活动,当发生的时候将会被关注:

  • 在 Pull Request 中的评论。
  • 在 Pull Request 分支中新提交的 commit。
  • 在 Pull Request 范围内的 commit 中的存在的文件和行注释。

Pull Request 的评论是 Markdown 语法兼容的,所以你可以嵌入图像,使用预格式化文本块,或者其他 Markdown 支持的格式。

查看长时间存留的 Pull Request

当一个功能或 bug 修正去了几个月,但从来没有通过或者丢弃,你经常想要仔细看看,是什么阻止这个 Pull Request 被解决。查看旧的但仍然活跃的 Pull Request,可以使得这个工作简化。

您可以从您的版本库的 Pull Request 页面查看和排序长时间存在的 Pull Request。

排序Pull Request

长期存在的 Pull Request 是至少已经存在了一个多月,并已在过去一个月内有可见活动的。该过滤器将按这样一个排序方式显示那些长期运行的 Pull Request:从创作到最新的活动的时间。(完)