如何在GitHub上贡献一个开源项目

【翻译】【教程】如何在GitHub上贡献一个开源项目

---

原文地址：The beginner’s guide to contributing to a GitHub project

如何在 GitHub 上贡献一个开源项目（以ZendFramework这个项目为例，但方法是通用的）。

---

第一步：在你的电脑上创建一份项目的拷贝

首先要把你感兴趣的项目的仓库拷贝到你自己的 GitHub 账户：只要在那个项目按下“fork”就可以了。完成之后可以在自己的GitHub里看到它是被 fork 来的：

现在需要把它从GitHub克隆到本地（你的电脑上），在右边栏找到“SSH clone URL”，在命令行输入下面的命令把项目克隆到本地：

$ git clone [email protected]:akrabat/zend-validator.git

注：首先要先安装git

执行结果：

切换到这个项目目录:

$ cd zend-validator

最后需要为本地仓库设置一个指向源仓库的远程地址，这样就可以把源仓库的改动同步到本地了。首先点击源仓库（forked from 的那个仓库）的链接跳转到它的 GitHub 主页面，把它的“SSH clone URL”地址加进远程地址里，命名为upstream：

$ git remote add upstream [email protected]:zendframework/zend-validator.git

现在你磁盘上的这个项目有了两个远程地址：

1. origin : 指向你 fork 到自己 GitHub 里的那个远程仓库，可以随意提交自己的更改。
2. upstream: 指向源仓库，只能从这个仓库拉取改动。

第二步：想办法让它在你的电脑上运行起来

有了源代码，还得让它在你的电脑上运行起来。不知道何从下手的话可以看看项目的 README 或 INSTALL 文件。

如果你成功把代码运行起来了，但是在这个过程中你发现项目的帮助文档并不完善，那么你的第一个 PR 就应该是修改这个帮助文档。经常会有这种情况，我（指作者）常常会把更新项目的 getting-started 文档作为第一个 PR !

第三步：做一些你自己的更改

这里就要开始对项目做出你自己的贡献了。最好是从修复一个让你烦恼的bug开始，或者是修复在“issue”栏上面发现的bug。如果实在不知道从哪里开始下手，很多项目也会用“easy pick”标签(或其它什么形式)来表示这个问题可以由项目的新成员来解决。

在issue中选好一个要解决的问题，然后在你的版本上复现这个问题。复现了问题之后再通过阅读代码找出原因所在。一旦发现了代码问题，就可以开始着手修复它了。

分支！

首要原则是在正确的分支上做你的工作。

如果是一个 git-flow 的项目，那么它会有 master 和 develop 分支。一般的原则是，在master分支上修复 bug ，在develop分支上添加新功能（feature）。 如果项目只有一个主分支那就用主分支。 一些项目用版本号来命名对应的分支（比如 Slim 是 2.x 和 3.x ），这时候就选择你用的分支。

比如我们正在修复 zend-validator 中的一个 bug，所以我们 checkout 到 master 分支上:

$ git checkout master
$ git pull upstream master && git push origin master
$ git checkout -b hotfix/readme-update

首先切换到主分支。然后用 git pull 命令从源项目仓库拉取更新到我们的本地仓库，再用 git push 命令同步这些更新到我们 fork 到 GitHub 上的远程仓库。最后创建自己的新分支，虽然可以随便命名，但最好还是起个有意义的名字，带上发行号的话会很有帮助。如果是像 zend-validator 那样使用 git-flow 的项目，还会有一些特殊的命名要求，分支的前缀应为“hotfix/”或“feature/”。

现在终于可以开始在这个分支上做你自己的修改了。

如果项目本身带有一些测试的话，为了确保你没有破坏任何东西，你要把它们都运行一遍。你也可以添加一个新的测试来表明你做的修改修复了原来的问题。

只修复你正在解决的问题。不要试图修复过程中发现的其他问题（包括格式问题），不然你的PR可能会被拒绝。

注：可以开新的PR去解决这些问题

确保按照逻辑单元提交(commit)代码，每次提交时写的提交信息要符合规范。可以参考 Tim Pope 的《A Note About Git Commit Messages》。

第四步：创建PR(Pull Request)

要创建一个PR，你只需要将分支推（push）到 fork 来的远程仓库，再按按 GitHub 上的一些按钮就好。

把新分支推到远程仓库：

$ git push -u origin hotfix/readme-update

你在 GitHub 上的项目里就会出现对应的分支。-u 表示把这个分支和远程的链接起来，以后只需要键入 git push origin 即可。

切回浏览器到项目的分支（在这个例子里是https://github.com/akrabat/zend-validator），可以看到新分支在顶部列出了一个方便的“Compare & pull request”按钮:

按下“Compare & pull request”！

如果出现一个这样的黄框:

点击链接会跳到项目的 CONTRIBUTING 文件，内容主要是如何使用项目代码以及如何对项目做贡献。

在接下来的页面上，确保“base fork”指向了正确的仓库和分支。然后给你的 pull request 起一个好的、简洁的标题，并在 description 框里说明你为什么要创建这个 pull request。如果有相关的 issue 编号记得也加上去。

再往向下滚动可以看到详细的更改细节。检查检查你修改的内容。

觉得没什么问题了，按下“Create pull request”，大功告成。

第五步：等待维护人员审核

为了把修改合并到项目里，维护人员会审核你的工作，然后合并它或是请你修改。

Lorna Mitchell的文章 《Code Reviews: Before You Even Run The Code》 涵盖了维护人员需要做哪些审核的工作，所以你也应该读读这个好让他们的工作轻松一点。

总而言之

以上就是全部的流程，总结成以下几点：

1. Fork 项目并克隆到本地。
2. 创建一个 upstream 远程地址，在创建新的分支之前先同步最新的修改到本地。
3. 为每个工作创建一个单独的分支。
4. 完成工作，写好你的提交信息，如果项目有 CONTRIBUTING 文件，好好阅读一下。
5. Push 分支到你自己的远程仓库。
6. 在 GitHub 上创建一个 PR 。
7. 等待代码审核的结果。

如果你想为一个开源项目做出贡献，最好的选择就是你自己正在使用的项目。维护者会很感激的!

---

词汇量将将过百，翻译文档纯属个人兴趣爱好，如有错误还请批评指出^_