转帖：向开源项目贡献源码（以 Orchard 为例）

原文地址：http://yangw80.blog.163.com/blog/static/247518002201552692516908/

在开源项目满天飞的时代，仅仅把开源项目拿来用是不够的，要适当的参与到开源项目的修改中，这对自己，对别人，都有很大意义。比如你在用项目 A 的 2.0 版本，你修改了 5 个地方并且都没有把修改贡献给项目 A，只是自己用。当项目更新到 3.0 版本的时候，你发现多了很多有趣的功能（自然没有包括自己修改的 5 个地方），于是你更新 3.0 的步骤就会麻烦许多。同时，你做的 5 个修改是否对项目的其他地方存在潜在影响？提交代码后，会有大牛审核，帮你发现问题。以上只是举例，相信其中的利弊大家都可以理解。 

现在以微软的开源项目 Orchard 为例，讲解一下如何参与该项目的代码维护。 

一、准备工作 

1. 注册一个 github 账号。
Orchard 源码托管在 github 上，所以首先，要去 https://github.com 注册一个账号，然后登陆。 

2. 安装并配置 git 客户端。
git 客户端可以在这里下载：https://windows.github.com/。安装成功后，桌面会出现两个图标： 

GitHub 是图形界面，Git Shell 控制台界面。网络上到处都有控制台界面下 git 命令行的用法，我也不想重复写 git 教程，所以本文只说一个最简单的通过图形界面贡献源码的步骤。 

双击 GitHub 图标，进入图形界面。首次使用会启动配置向导，在“Log in”步骤输入你在 github 网站注册的用户名和密码，点击 Log in 登陆： 

在 Configure 步骤输入你在 github 网站的用户名和邮箱，点击 Continue 继续： 

在 Repositories 步骤选择一个自己的仓库。由于我们还没有创建自己的仓库，点 Skip 跳过： 

然后进入了空空的主界面： 

二、了解一些基本知识 

1. 关于 Orchard 项目：
Orchard 项目的官网：http://www.orchardproject.net/
Orchard 源码的 github 页面：https://github.com/OrchardCMS/Orchard
后面要做的提交源码，都在 github 网站和客户端上操作。
进入 Orchard 的 github 页面后，可以点一下右上角的 Star 按钮将项目收藏起来，也算是表达一下对项目的喜欢： 

2. 关于支路（Fork）和分支（Branch）
为了确保大家可以同时修改项目，每个人都可以创建一份项目的支路（Fork），并在自己的支路（Fork）上操作。
每一个支路（Fork）下面都可以有许多分支（Branch），用于保存项目不同时期的不同状态。
看一下 Orchard 项目下面的分支（Branch）： 

Orchard 当前最新版本是 1.9.1，切换到 1.9.1 分支后，在下面的文件列表中可以直接在线浏览源码。 

3. 提交代码所涉及的分支（Branch）
提交代码的时候，有两个分支需要注意：1.9.x 和 dev。
其中，bug 一类的修改，可以提交到 1.9.x 分支；新功能一类的修改，可以提交到 dev 分支。随着项目的不断发展，每个分支的含义可能会调整，详见官网文档：http://docs.orchardproject.net/Documentation/Contributing-patches。 

三、获取一份可以修改的源码 

1. 创建支路（Fork）。 

修改源码前，首先要通过 GitHub 网站创建一份自己的支路（Fork）（即源代码的完整拷贝）：

大约等上 10 秒钟就好，然后系统会自动切换到自己的支路： 

2. 通过 GitHub 客户端，将支路代码同步到本地。 

打开 GitHub 客户端：点左上角 + 号，切换到 Clone 选项卡，会发现之前 Fork 出来的 Orchard 支路。选中，然后点 Clone：

然后选择源码将要保存到的本地路径，开始克隆（Clone）操作： 

Orchard 项目的文件比较多，过程比较漫长，需要耐心等会儿。根据网速不同，大概需要十多分钟甚至半个小时。克隆完毕后，会看到项目有 0 changes 和 0 unsynced： 

至此，代码已经成功同步到本地。 

四、修改源码
做为范例，本文提交一个 Orchard 的小 bug 到 1.9.x 分支。前面说过，bug 一类的修改是约定在 1.9.x 分支上进行的。切换默认的 dev 分支为 1.9.x 分支： 

用 Visual Studio 2013 打开 Orchard 源码，打开文件：Orchard/src/Orchard.Web/Modules/Orchard.Taxonomies/Views/Fields/TaxonomyField.cshtml，发现这里多了一个 @ 符号，删掉，并保存文件： 

（注意：任何修改都务必谨慎，并在本地调试无误）
然后切换到 GitHub 客户端，会自动发现有一个修改（change），选中修改文件，右边可以显示出修改前后的内容，可以检查一下。在底部填写本次修改的说明（说明请用英文描述）： 

点底部的“Commit to 1.9.x”会将修改提交到本地仓库。之后，会看到有一个没有同步的项目，点Sync，将项目同步到远程仓库： 

同步完成后，状态会变为0 changes，0 unsynced。 

五、贡献代码 

之前的操作，只是将代码同步到了你 Fork 出来的远程仓库，只是源码的一个支路，并不会影响原项目。当你确认修改无误后，你可以向原项目发一个 pull request 请求，通知项目管理员合并你的代码。步骤如下： 

1. 进入之前 fork 出来的项目，切换分支到 1.9.x，刚才的修改就是在这个分支下做的。点击左边的“Compare、review、create a pull request”按钮： 

之后进入的页面会将所有修改列出来，检查一下有没有错误。如果没错，就点击“Create pull request”按钮： 

在接下来进入的页面中填写本次修改的描述，用英文简单描述一下自己的修改内容，然后点击“Create pull request”发出请求： 

确认后，进入如下页面，可以看到自己提交修态的状态是“Open”： 

项目管理员会在上面的页面中跟你讨论你的修改是否有问题。如果没问题，会通过你的合并代码请求，然后自己提交代码修改的状态会变为“Merged”： 

这就表示你的代码已经分享给了全世界~~。 

这时候，大家可以在 github 网站右边的 Pulse 选项卡里看到你的提交： 

大家下载 1.9.x 的源码时，也会包含你的提交。 

同时，你在 1.9.x 分支的修改会在一段时间后同步到 dev 分支，并且成为下一个正式版中的一部分。 

六、其他贡献 

除了提交代码以外，也可以提交 bug 或建议。 

进入 github 网站，在右侧切换到 Issues 选项卡（叹号图标），点击 New issue 可以提交一个新的问题，过程就像在论坛发帖一样简单，不再详述。 

同时，你也可以浏览别人遇到的问题，如果你可以解决某个问题，请在提交代码之后的描述中，填写相关的问题编号，例如你会看到曾经有这样的描述： 

Issue #5426 Projections don't order queries following Position field 

这就表示这个提交的代码是解决的编号为 #5426 的问题。 

当你解决相关的问题并提交代码后，记得去 Issues 页面回帖说自己解决了这个问题，并在回帖中提供 pull 请求的编号及地址，方便大家查看。 

欢迎你成为开源世界的一员~~。 

原文地址：http://yangw80.blog.163.com/blog/static/247518002201552692516908/