注册 登录  
 加关注
   显示下一条  |  关闭
温馨提示!由于新浪微博认证机制调整,您的新浪微博帐号绑定已过期,请重新绑定!立即重新绑定新浪微博》  |  关闭

杨伟的博客

程序人生

 
 
 

日志

 
 

向开源项目贡献源码(以 Orchard 为例)  

2015-06-27 11:56:24|  分类: Orchard |  标签: |举报 |字号 订阅

  下载LOFTER 我的照片书  |

在开源项目满天飞的时代,仅仅把开源项目拿来用是不够的,要适当的参与到开源项目的修改中,这对自己,对别人,都有很大意义。比如你在用项目 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/。安装成功后,桌面会出现两个图标:

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

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

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

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

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

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

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

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

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

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

 

二、了解一些基本知识


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

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客


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

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

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)(即源代码的完整拷贝):
向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

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

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

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

打开 GitHub 客户端:点左上角 + 号,切换到 Clone 选项卡,会发现之前 Fork 出来的 Orchard 支路。选中,然后点 Clone:
向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

然后选择源码将要保存到的本地路径,开始克隆(Clone)操作:

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

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

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

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

 

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

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

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

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

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

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

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

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

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

 

五、贡献代码

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


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

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

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

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

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

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

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

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

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

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

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

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

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

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

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

注意:

如果不打算再提交代码,请删掉自己 Fork 出来的支路:切换到自己的支路代码(例如我的支路代码是https://github.com/yw80/Orchard),点击右侧最后一个选项卡“Settings”,最底部有按钮“Delete this repository”,点击后会弹出对话框确认,输入自己的项目名称“Orchard”,然后确认即可。

 

六、更新代码

大家 Fork 出来的支路,可以认为是源代码的一个静态拷贝。换句话说,如果原项目有了更新,那么自己 Fork 出来的代码是不会自动应用这些更新的。这很好理解,因为谁也不希望自己正在修改的代码莫名其妙的改变吧?

所以,也许某个时候,你会想把原项目中的更新,合并到自己的支路代码中(和前面的“贡献代码”正好相反)。这一节就讲这个问题。

假设现在需要更新 dev 分支的代码。

1. 方法一:先更新远程仓库代码,再同步到本地

首先,要在自己的支路代码页面,切换到 dev 分支(参见二.2)。然后击左边的“Compare、review、create a pull request”按钮(参见五.1)。

默认界面是检查是否有需要提交的代码。当然,目前没有找到需要提交的代码。点击下面的链接“switching the base”,切换到更新代码(即“向自己提交代码”):

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

接下来的界面,显示的是源代码相对于自己 Fork 出来的支路代码,有了哪些更新。点击 Create pull request 创建合并代码请求:

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

 填写合并代码的理由,点击 Create pull request:

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

 在页面靠下的位置,点击 Merge pull request,确认合并代码:

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客
 

 填写理由,点击 Confirm merge,确认合并代码:

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客
 

打开客户端程序 GitHub,切换到 dev 分支,会发现 Sync 提示需要同步的内容,点击 Sync 同步:

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

现在,你本地的 dev 分支,已经更新了最新的代码。

2. 方法二:先更新本地代码,再同步到远程仓库

在本地切换到 dev 分支,然后点击分支列表中的 Manage:

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

在打开的分支管理界面中,拖动本地的 dev 和远程的原 OrchardCMS/dev 分支到底部,然后点 Merge 执行合并:

向开源项目贡献源码(以 Orchard 为例) - yw80 - 杨伟的博客

合并之后,再点界面右上角的 Sync 将最新代码同步到远程仓库即可。

 

七、真实应用

前面只是简单说了一下基本使用方法。而实际中,这么做会有一些麻烦,比如你无法同时修改两个功能。

实际中,每个人都有自己的习惯,我说一下我的:

Orchard 地址是:OrchardCMS/Orchard

我 Fork 出来的项目地址是:yw80/Orchard

然后,比如我想修改一个 bug,我会基于 1.9.x 分支(branch)创建一个新分支(branch)叫 patch-1,然后切换到 patch-1 分支工作,修改自己需要改的代码,然后提交;

如果我还需要提交另一个 bug,我会再基于 1.9.x 分支(branch)创建一个新分支(branch)叫 patch-2,然后切换到 patch-2 分支工作,修改自己需要改的代码,然后提交;

如果官方审核通过了提交,就可以直接在本地删掉 patch-1 或 patch-2 分支了。

同时,yw80/Orchard/1.9.x 分支可以用来获取最新代码。

对了,你还可以选择一款更强大的 Git 客户端工具,例如 Windows 下面的 Git Extensions 就很不错。

 

八、其他贡献

除了提交代码以外,还可以帮助 Orchard 翻译为本地语言,请参考我的另一篇文章《讲解如何参与 Orchard 的中文翻译工作》:http://yangw80.blog.163.com/blog/static/24751800220155202451781/

也可以向 Orchard 提交 bug 或建议:进入 github 网站,在右侧切换到 Issues 选项卡(叹号图标),点击 New issue 可以提交一个新的问题,过程就像在论坛发帖一样简单,不再详述。

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

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

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

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

 

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

  评论这张
 
阅读(459)| 评论(0)
推荐 转载

历史上的今天

评论

<#--最新日志,群博日志--> <#--推荐日志--> <#--引用记录--> <#--博主推荐--> <#--随机阅读--> <#--首页推荐--> <#--历史上的今天--> <#--被推荐日志--> <#--上一篇,下一篇--> <#-- 热度 --> <#-- 网易新闻广告 --> <#--右边模块结构--> <#--评论模块结构--> <#--引用模块结构--> <#--博主发起的投票-->
 
 
 
 
 
 
 
 
 
 
 
 
 
 

页脚

网易公司版权所有 ©1997-2017