6.2 对项目做出贡献

对项目做出贡献

账户已经建立好了，现在我们来了解一些能帮助你对现有的项目做出贡献的知识。

派生（Fork）项目

如果你想要参与某个项目，但是并没有推送权限，这时可以对这个项目进行“派生”。派生的意思是指，GitHub 将在你的空间中创建一个完全属于你的项目副本，且你对其具有推送权限。

在以前，“fork”是一个贬义词，指的是某个人使开源项目向不同的方向发展，或者创建一个竞争项目，使得原项目的贡献者分裂。在 GitHub，“fork”指的是你自己的空间中创建的项目副本，这个副本允许你以一种更开放的方式对其进行修改。

通过这种方式，项目的管理者不再需要忙着把用户添加到贡献者列表并给予他们推送权限。人们可以派生这个项目，将修改推送到派生出的项目副本中，并通过创建合并请求（Pull Request）来让他们的改动进入源版本库，下文我们会详细说明。创建了合并请求后，就会开启一个可供审查代码的板块，项目的拥有者和贡献者可以在此讨论相关修改，直到项目拥有者对其感到满意，并且认为这些修改可以被合并到版本库。

你可以通过点击项目页面右上角的“Fork”按钮，来派生这个项目。

将派生出的副本克隆到本地

创建出名称有意义的分支

修改代码

检查改动

将改动提交到分支中

将新分支推送到 GitHub 的副本中

现在到 GitHub 上查看之前的项目副本，可以看到 GitHub 提示我们有新的分支，并且显示了一个大大的绿色按钮让我们可以检查我们的改动，并给源项目创建合并请求。

你也可以到“Branches”（分支）页面查看分支并创建合并请求： https://github.com/<用户名>/<项目名>/branches

Figure 6-11. 合并请求创建页面

当你单击了“Create pull request”（创建合并请求）的按钮后，这个项目的拥有者将会收到一条包含关改动和合并请求页面的链接的提醒。

虽然合并请求通常是在贡献者准备好在公开项目中提交改动的时候提交，但是也常被用在仍处于开发阶段的内部项目中。因为合并请求在提交后 依然可以加入新的改动 ，它也经常被用来建立团队合作的环境，而不只是在最终阶段使用。

利用合并请求

现在，项目的拥有者可以看到你的改动并合并它，拒绝它或是发表评论。在这里我们就当作他喜欢这个点子，但是他想要让灯熄灭的时间比点亮的时间稍长一些。

接下来可能会通过电子邮件进行互动，就像我们在 Chapter 5 中提到的工作流程那样，但是在 GitHub，这些都在线上完成。项目的拥有者可以审查修改，只需要单击某一行，就可以对其发表评论。

Figure 6-13. 通过电子邮件发送的评论提醒

每个人都能在合并请求中发表评论。在 Figure 6-14 里我们可以看到项目拥有者对某行代码发表评论，并在讨论区留下了一个普通评论。你可以看到被评论的代码也会在互动中显示出来。

Figure 6-15. 最终的合并请求

如果你点开合并请求的“Files Changed”（更改的文件）选项卡，你将会看到“整理过的”差异表 —— 也就是这个分支被合并到主分支之后将会产生的所有改动，其实就是 git diff master...<分支名> 命令的执行结果。你可以浏览 “确定引入了哪些东西” 来了解更多关于差异表的知识。

你还会注意到，GitHub 会检查你的合并请求是否能直接合并，如果可以，将会提供一个按钮来进行合并操作。这个按钮只在你对版本库有写入权限并且可以进行简洁合并时才会显示。你点击后 GitHub 将做出一个“非快进式”（non-fast-forward）合并，即使这个合并 能够 快进式（fast-forward）合并，GitHub 依然会创建一个合并提交。

如果你需要，你还可以将分支拉取并在本地合并。如果你将这个分支合并到 master 分支中并推送到 GitHub，这个合并请求会被自动关闭。

这就是大部分 GitHub 项目使用的工作流程。创建分支，基于分支创建合并请求，进行讨论，根据需要继续在分支上进行修改，最终关闭或合并合并请求。

不必总是 Fork

有件很重要的事情：你可以在同一个版本库中不同的分支提交合并请求。如果你正在和某人实现某个功能，而且你对项目有写权限，你可以推送分支到版本库，并在 master 分支提交一个合并请求并在此进行代码审查和讨论的操作。不需要进行“Fork”。

合并请求的进阶用法

目前，我们学到了如何在 GitHub 平台对一个项目进行最基础的贡献。现在我们会教给你一些小技巧，让你可以更加有效率地使用合并请求。

将合并请求制作成补丁

有一件重要的事情：许多项目并不认为合并请求可以作为补丁，就和通过邮件列表工作的的项目对补丁贡献的看法一样。大多数的 GitHub 项目将合并请求的分支当作对改动的交流方式，并将变更集合起来统一进行合并。

这是个重要的差异，因为一般来说改动会在代码完成前提出，这和基于邮件列表的补丁贡献有着天差地别。这使得维护者们可以更早的沟通，由社区中的力量能提出更好的方案。当有人从合并请求提交了一些代码，并且维护者和社区提出了一些意见，这个补丁系列并不需要从头来过，只需要将改动重新提交并推送到分支中，这使得讨论的背景和过程可以齐头并进。

举个例子，你可以回去看看 Figure 6-15，你会注意到贡献者没有变基他的提交再提交一个新的合并请求，而是直接增加了新的提交并推送到已有的分支中。如果你之后再回去查看这个合并请求，你可以轻松地找到这个修改的原因。点击网页上的“Merge”（合并）按钮后，会建立一个合并提交并指向这个合并请求，你就可以很轻松的研究原来的讨论内容。

与上游保持同步

如果你的合并请求由于过时或其他原因不能干净地合并，你需要进行修复才能让维护者对其进行合并。GitHub 会对每个提交进行测试，让你知道你的合并请求能否简洁的合并。

“变基的风险” 中提到的问题。相对的，将变基后的分支推送到 GitHub 上的一个新分支中，并且创建一个全新的合并请求引用旧的合并请求，然后关闭旧的合并请求。

参考

你的下个问题可能是“我该如何引用旧的合并请求？”。有许多方法可以让你在 GitHub 上的几乎任何地方引用其他东西。

先从如何对合并请求或议题（Issue）进行相互引用开始。所有的合并请求和议题在项目中都会有一个独一无二的编号。举个例子，你无法同时拥有 3 号合并请求和 3 号议题。如果你想要引用任何一个合并请求或议题，你只需要在提交或描述中输入 #<编号> 即可。你也可以指定引用其他版本库的议题或合并请求，如果你想要引用其他人对该版本库的“Fork”中的议题或合并请求，输入 用户名#<编号> ，如果在不同的版本库中，输入 用户名/版本库名#<编号> 。

我们来看一个例子。假设我们对上个例子中的分支进行了变基，并为此创建一个新的合并请求，现在我们希望能在新的合并请求中引用旧的合并请求。我们同时希望引用一个派生出的项目中的议题和一个完全不同的项目中的议题，就可以像 Figure 6-18 这样填写描述。

Figure 6-20 中展示的那样。

Figure 6-22 这样。

如果加入语言的名称，就像我们这里加入的“java”一样，GitHub 会自动尝试对摘录的片段进行语法高亮。在下面的例子中，它最终会渲染成这个样子： Figure 6-24 。

图片

从技术层面来说，这并不是 GitHub 风格 Markdown 的功能，但是也很有用。如果不想使用 Markdown 语法来插入图片，GitHub 允许你通过拖拽图片到文本区来插入图片。