MRCODE-BOOK

# 对项目作出贡献

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

# 派生（Fork）项目

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

TIP

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

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

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

“Fork”按钮.

稍等片刻，你将被转到新项目页面，该项目包含可写的代码副本。

# GitHub 流程

GitHub 设计了一个 以合并请求为中心的特殊合作流程。 它基于我们在 Git 分支 的 特性分支 中提到的工作流程。 不管你是在一个紧密的团队中使用单独的版本库，或者使用许多的 “Fork” 来为一个由陌生人组成的国际企业或网络做出贡献，这种合作流程都能应付。

流程通常如下：

  1. 从 master 分支中创建一个新分支
  2. 提交一些修改来改进项目
  3. 将这个分支推送到 GitHub 上
  4. 创建一个合并请求
  5. 讨论，根据实际情况继续修改
  6. 项目的拥有者合并或关闭你的合并请求

这基本和 集成管理者工作流 中的一体化管理流程差不多，但是团队可以使用 GitHub 提供的网页工具替代电子邮件来交流和审查修改。

现在我们来看一个使用这个流程的例子。

# 创建合并请求

Tony 在找一些能在他的 Arduino 微控制器上运行的代码，他觉得 https://github.com/schacon/blink 中的代码不错。

他想要做出贡献的项目

但是有个问题，这个代码中的的闪烁频率太高，我们觉得 3 秒一次比 1 秒一次更好一些。 所以让我们来改进这个程序，并将修改后的代码提交给这个项目。

首先，单击 “Fork” 按钮来获得这个项目的副本。 我们使用的用户名是 “tonychacon”，所以这个项目副本的访问地址是： https://github.com/tonychacon/blink 。 我们将它克隆到本地，创建一个分支，修改代码，最后再将改动推送到 GitHub。

$ git clone https://github.com/tonychacon/blink (1) Cloning into 'blink'...

$ cd blink
$ git checkout -b slow-blink (2) Switched to a new branch 'slow-blink'

$ sed -i '' 's/1000/3000/' blink.ino (3) $ git diff --word-diff (4) diff --git a/blink.ino b/blink.ino
index 15b9911..a6cc5a5 100644
--- a/blink.ino
+++ b/blink.ino
@@ -18,7 +18,7 @@ void setup() {
// the loop routine runs over and over again forever:
void loop() {
  digitalWrite(led, HIGH);   // turn the LED on (HIGH is the voltage level)
  [-delay(1000);-]{+delay(3000);+}               // wait for a second
  digitalWrite(led, LOW);    // turn the LED off by making the voltage LOW
  [-delay(1000);-]{+delay(3000);+}               // wait for a second
}

$ git commit -a -m 'three seconds is better' (5) [slow-blink 5ca509d] three seconds is better
 1 file changed, 2 insertions(+), 2 deletions(-)

$ git push origin slow-blink (6) Username for 'https://github.com': tonychacon
Password for 'https://tonychacon@github.com':
Counting objects: 5, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 340 bytes | 0 bytes/s, done.
Total 3 (delta 1), reused 0 (delta 0)
To https://github.com/tonychacon/blink
 * [new branch]      slow-blink -> slow-blink
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
  1. 将派生出的副本克隆到本地
  2. 创建出名称有意义的分支
  3. 修改代码
  4. 检查改动
  5. 将改动提交到分支中
  6. 将新分支推送到 GitHub 的副本中

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

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

img

上图中绿色按钮是 合并请求按钮

如果你点击了那个绿色按钮，就会看到一个新页面，在这里我们可以对改动填写 标题和描述，让项目的拥有者考虑一下我们的改动。通常花点时间来编写个清晰有用的描述是个不错的主意，这能让作者明白为什么这个改动可以给他的项目带来好处，并且让他接受合并请求。

同时我们也能看到比主分支中所 “领先”（ahead）的提交（在这个例子中只有一个）以及所有将会被合并的改动与之前代码的对比。

合并请求创建页面

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

TIP

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

# 利用合并请求

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

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

对合并请求内的特定一行发表评论：

img

当维护者发表评论后，提交合并请求的人，以及所有正在关注（Watching）这个版本库的用户都会收到通知。我们待会儿将会告诉你如何修改这项设置。现在，如果 Tony 有开启电子邮件提醒，他将会收到这样的一封邮件：

通过电子邮件发送的评论提醒：

电子邮件提醒

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

合并请求讨论页面：

合并请求讨论页面

现在贡献者可以看到如何做才能让他们的改动被接受。幸运的是，这也是一件轻松的事情。如果你使用的是电子邮件进行交流，你需要再次对代码进行修改并重新提交至邮件列表，在 GitHub 上，你只需要再次提交到你的分支中并推送即可。

如果贡献者完成了以上的操作，项目的拥有者会再次收到提醒，当他们查看页面时，将会看到最新的改动。事实上，只要提交中有一行代码改动，GitHub 都会注意到并处理掉旧的变更集。

最终的合并请求：

最终的合并请求

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

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

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

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

不必总是 Fork

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

# 合并请求的进阶用法

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

# 将合并请求制作成补丁

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

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

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

# 与上游保持同步

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

能进行干净合并：

合并请求合并失败

如果你看到了像上图中的画面，你就 需要修复你的分支让这个提示变成绿色，这样维护者就不需要再做额外的工作。

你有两种方法来解决这个问题。你 可以把你的分支变基到目标分支中去（通常是你派生出的版本库中的 master 分支），或者你 可以合并目标分支到你的分支中去。

GitHub 上的 大多数的开发者会使用后一种方法，基于我们在上一节提到的理由：我们最看重的是历史记录和最后的合并，变基除了给你带来看上去简洁的历史记录，只会让你的工作变得更加困难且更容易犯错。

如果你想要合并目标分支来让你的合并请求变得可合并，你需要将源版本库添加为一个新的远端，并从远端抓取内容，合并主分支的内容到你的分支中去，修复所有的问题并最终重新推送回你提交合并请求使用的分支。

在这个例子中，我们再次使用之前的 “tonychacon” 用户来进行示范，源作者提交了一个改动，使得合并请求和它产生了冲突。现在来看我们解决这个问题的步骤。

$ git remote add upstream https://github.com/schacon/blink (1) $ git fetch upstream (2) remote: Counting objects: 3, done.
remote: Compressing objects: 100% (3/3), done.
Unpacking objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0)
From https://github.com/schacon/blink
 * [new branch]      master     -> upstream/master

$ git merge upstream/master (3) Auto-merging blink.ino
CONFLICT (content): Merge conflict in blink.ino
Automatic merge failed; fix conflicts and then commit the result.

$ vim blink.ino (4) $ git add blink.ino
$ git commit
[slow-blink 3c8d735] Merge remote-tracking branch 'upstream/master' \
    into slower-blink

$ git push origin slow-blink (5) Counting objects: 6, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (6/6), done.
Writing objects: 100% (6/6), 682 bytes | 0 bytes/s, done.
Total 6 (delta 2), reused 0 (delta 0)
To https://github.com/tonychacon/blink
   ef4725c..3c8d735  slower-blink -> slow-blink
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
  1. 将源版本库添加为一个远端，并命名为 “upstream”（上游）
  2. 从远端抓取最新的内容
  3. 将主分支的内容合并到你的分支中
  4. 修复产生的冲突
  5. 再推送回同一个分支

你完成了上面的步骤后，合并请求将会自动更新并重新检查是否能干净的合并。

合并请求现在可以干净地合并了：

修复了的合并请求

Git 的伟大之处就是你可以一直重复以上操作。如果你有一个运行了十分久的项目，你可以轻松地合并目标分支且只需要处理最近的一次冲突，这使得管理流程更加容易。

如果你一定想对分支做变基并进行清理，你可以这么做，但是强烈建议你不要强行的提交到已经提交了合并请求的分支。如果其他人拉取了这个分支并进行一些修改，你将会遇到 变基的风险 中提到的问题。相对的，将变基后的分支推送到 GitHub 上的一个新分支中，并且创建一个全新的合并请求引用旧的合并请求，然后关闭旧的合并请求。

# 参考

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

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

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

在合并请求中的交叉引用：

合并请求中的引用

当我们提交了这个合并请求，我们将会看到以上内容被渲染成这样：

渲染后的合并请求中的引用

你会注意到完整的 GitHub 地址被简化了，只留下了必要的信息。

如果 Tony 回去关闭了源合并请求，我们可以看到一个被引用的提示，GitHub 会自动的反向追踪事件并显示在合并请求的时间轴上。这意味着任何查看这个合并请求的人可以轻松地访问新的合并请求。这个链接就像 在合并请求中渲染后的交叉引用 中展示的那样。

在合并请求中渲染后的交叉引用：

合并请求关闭

除了议题编号外，你 还可以通过使用提交的 SHA-1 来引用提交。你必须完整的写出 40 位长的 SHA，GitHub 会在评论中自动地产生指向这个提交的链接。同样的，你可以像引用议题一样对 “Fork” 出的项目中的提交或者其他项目中的提交进行引用。

# Markdown

对于在 GitHub 中绝大多数文本框中能够做到的事，引用其他议题只是个开始。在议题和合并请求的描述，评论和代码评论还有其他地方，都可以使用 **“GitHub 风格的 Markdown” ** 。Markdown 可以让你输入纯文本，但是渲染出丰富的内容。

如下图 Markdown 的例子和渲染效果

Markdown 例子

# GitHub 风格的 Markdown

GitHub 风格的 Markdown 增加了一些基础的 Markdown 中做不到的东西。它在创建合并请求和议题中的评论和描述时十分有用。

# 任务列表

第一个 GitHub 专属的 Markdown 功能，特别是用在合并请求中，就是任务列表。一个任务列表可以展示出一系列你想要完成的事情，并带有复选框。把它们放在议题或合并请求中时，通常可以展示你想要完成的事情。

你可以这样创建一个任务列表：

- [X] 编写代码
- [ ] 编写所有测试程序
- [ ] 为代码编写文档
1
2
3

如果我们将这个列表加入合并请求或议题的描述中，它将会被渲染成如下图这样

任务列表示例

在合并请求中，任务列表经常被用来在合并之前展示这个分支将要完成的事情。最酷的地方就是，你只需要点击复选框，就能更新评论 —— 你不需要直接修改 Markdown。

不仅如此，GitHub 还会将你在议题和合并请求中的任务列表整理起来集中展示。举个例子，如果你在一个合并请求中有任务清单，你将会在所有合并请求的总览页面上看到它的进度。这使得人们可以把一个合并请求分解成不同的小任务，同时便于其他人了解分支的进度。

在合并请求列表中的任务列表总结：

任务列表示例

当你在实现一个任务的早期就提交合并请求，并使用任务清单追踪你的进度，这个功能会十分的有用。

# 摘录代码

你也可以在评论中摘录代码。这在你想要展示尚未提交到分支中的代码时会十分有用。它也经常被用在展示无法正常工作的代码或这个合并请求需要的代码。

你需要用 “反引号” 将需要添加的摘录代码包起来。

​```java
for(int i=0 ; i < 5 ; i++)
{
   System.out.println("i is : " + i);
}
​```
1
2
3
4
5
6

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

渲染后的摘录代码

# 引用

如果 你在回复一个很长的评论之中的一小段，你只需要复制你需要的片段，并在每行前添加 > 符号即可。事实上，因为这个功能会被经常用到，它也有一个快捷键。只要你把你要回应的文字选中，并按下 r 键，选中的问题会自动引用并填入评论框。

引用的部分就像这样:

> Whether 'tis Nobler in the mind to suffer
> The Slings and Arrows of outrageous Fortune,

How big are these slings and in particular, these arrows?
1
2
3
4

经过渲染后，就会变成这样：

渲染后的引用

# 表情符号（EMOJI）

最后，我们可以在评论中使用表情符号。这经常出现在 GitHub 的议题和合并请求的评论中。GitHub 上甚至有表情助手。如果你在输入评论时以 : 开头，自动完成器会帮助你找到你需要的表情。

表情符号自动完成器：

表情符号自动完成器

你也可以在评论的任何地方使用 :<表情名称>: 来添加表情符号。举个例子，你可以输入以下文字：

I :eyes: that :bug: and I :cold_sweat:.

:trophy: for :microscope: it.

:+1: and :sparkles: on this :ship:, it's :fire::poop:!

:clap::tada::panda_face:
1
2
3
4
5
6
7

渲染之后，就会变成这样：

使用了大量表情符号的评论：

Emoji

虽然这个功能并不是非常实用，但是它在这种不方便表达感情的媒体里，加入了趣味的元素。

TIP

事实上现在已经有大量的在线服务可以使用表情符号，这里有个列表可以让你快速的找到能表达你的情绪的表情符号：

http://www.emoji-cheat-sheet.com (opens new window)

# 图片

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

通过拖拽的方式自动插入图片：

拖拽插入图片

如果你回去查看 在合并请求中的交叉引用 ，你会发现文本区上有个 **“Parsed as Markdown” **的提示。点击它你可以了解所有能在 GitHub 上使用的 Markdown 功能。

← 维护项目 →