Github 对项目做出贡献

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

派生(Fork)项目

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

Note

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

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

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

GitHub 流程

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

流程通常如下:

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

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

创建合并请求

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

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

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

  1. 将派生出的副本克隆到本地
  2. 创建出名称有意义的分支
  3. 修改代码
  4. 检查改动
  5. 将改动提交到分支中
  6. 将新分支推送到 GitHub 的副本中

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

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

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

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

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

Note

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

利用合并请求

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

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

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

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

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

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