大家都知道Android是一个开源项目,那任何人都可以为其贡献代码,虽然在developer的网站上有详细的步骤(http://source.android.com/source/submit-patches.html#upstream-projects),但是按照其一步一步来也会遇到很多麻烦,在这里把我成功提交patch的步骤记录下来,一方面希望别人不要再走弯路,一方面也给对英文抵触的同学一个参考。
首先,简单介绍一下android官方的代码审核工具Gerrit,Gerrit 是基于git 的 项目管理工具和代码审核工具,网上关于git的介绍很多,推荐一本git 经典书籍《pro git》,因为android的源码就是git管理的,相信大家还会比较熟悉的。
git中文教程:http://www.cnblogs.com/zhangjing230/archive/2012/05/09/2489745.html
git快速入门:http://zhuidaniu.com/tutorials/22
继续说Gerrit,Gerrit是一个网页在线工具,所有外部提交的代码都要先提交到这个在线工具中等待代码审核,只有审核通过的代码才能并入到开源项目中,一旦审核通过,Gerrit 可以自动的merge代码到代码仓库中。
Android 项目 Gerrit传送门:https://android-review.googlesource.com/#/q/status:open,n,z
如果你对Gerrit感兴趣,想把Gerrit集成到你现在进行的项目上也是可以的,参考Geriit的开源项目: http://code.google.com/p/gerrit/
你还需要熟悉一下android官方提供的repo命令,repo是一个python脚本,其中对git命令进行了一个封装,repo可以同时下载多个git仓库。
Git,Repo,Gerrit的简单介绍以及提交补丁时候的基本工作流程:http://source.android.com/source/version-control.html
相信大家已经对怎么提交补丁到Android的开源项目有了个理论上的认识,接下来我们从实践出发真正提交个补丁上去,推荐使用Ubuntu作为android的源码开发环境。
1. 下载android的源码,只有基于源码才能提交我们的补丁,源码下载方法请参考 http://source.android.com/source/downloading.html, 源码下载可能需要几个小时或者几天的时间,视网络情况而定,国内网路连接android网站不是很稳定,如果遇到连接错误也没关系,repo sync 可以断点续传,有条件的可以使用VPN。
1.1 在本地创建一个代码目录,并下载repo脚本。
- $ mkdir ~/bin
- $ PATH=~/bin:$PATH //将~/bin #文件夹路径放入到系统路径,这样此路径下的命令在系统任何地方都可以被直接调用
- $ curl https://dl-ssl.google.com/dl/googlesource/git-repo/repo > ~/bin/repo #下载repo脚本到bin文件夹下
- $ chmod a+x ~/bin/repo #repo脚本默认没有执行权限,为它增加执行权限
1.2 安装并配置repo
在1.1中你已经把repo下载下来了,但是要想使用它还需要安装
我们创建一个单独的文件夹来装android的源码,并将repo安装到这个文件夹中:
- $ mkdir WORKING_DIRECTORY
- $ cd WORKING_DIRECTORY
- $ repo init -u https://android.googlesource.com/platform/manifest #这样默认下载的是master分支的源码
如果你想下载指定分支的源码,如android 4.0.1r1 的源码,可以使用-b选项来指定
- $ repo init -u https://android.googlesource.com/platform/manifest -b android-4.0.1_r1
这样repo就安装好了。
1.3 同步代码到本地。
- $repo sync
耐心地等待吧...
2. 配置Gerrit 登录密钥
首先你需要创建一个Google账户去登录到Gerrit Server, 如果你有Gmail,你可以直接登录,但注册谷歌账户不一定非得要gmail邮箱,其他邮箱也是可以的,这里我使用163邮箱申请个谷歌账户来登录Gerrit。
2.1 进入 https://android-review.googlesource.com/, 点击右上角 sign in,进入google 账户登录界面,如果你有gmail可以直接登录,否则点击create a new count 进入如下注册界面,填入你想显示的邮箱地址和其他相关信息,提交以后系统会向你填入的邮箱地址发封确认邮件。
2.2 打开自己的邮箱,点击确认链接,完成确认。
2.3 点击Continue后就登录到Gerrit了,但是我发现我的登录名是 Anonymous Coward <springnap@163.com>,之所以显示 Anonymous Coward是因为你没有设置显示的姓名,通过 Setings --> contact information --> Edit 可以设置你的显示姓名。
2.3.1
2.3.2
2.3.3
2.3.4 保存成功后返回Gerrit的contact information 页面,点击reload更新显示姓名。
现在再去看你Gerrit右上角的显示信息是不是不一样了?
2.4 在本地环境中配置Gerrit认证信息,用于向gerrit提交代码时候的身份认证。
2.4.1 还是在setting里面,点击 HTTP Password --> Obtain password 得到认证信息,然后将这些认证信息拷贝到你的~/.netrc 文件中, 如果有两行密码,那两行都要拷贝,
由于这写信息涉及身份认证信息,这里就不再截图了,记得不要把你的密码泄漏出去哦,不然任何人都可以冒充你提交代码了!
2.5 准备工作都做好了,终于可以动代码了!
2.5.1 提交补丁之前你必须创建一个新的代码分支,看看官方文档怎么说的:
Start a repo branch
For each change you intend to make, start a new branch within the relevant git repository:
$ repo start NAME .
You can start several independent branches at the same time in the same repository. The branch NAME is local to your workspace and will not be included on gerrit or the final source tree.
如果你照抄命令,你就会遇到 error: project . not found 的错误提示, 问题的关键在这句话里面
- For each change you intend to make, start a new branch within the relevant git repository
你们还记得之前提到repo的特色功能吗?就是同时下载多个git 仓库到本地,git 仓库的列表之前也提到过,是在android根目录/.repo(加点的都是隐藏的)/manifest.xml 中,比如我们改动的是packages/apps/Gallery2下的文件
看到了吧,Gallery2 项目的路径就是path属性的值,找到了项目路径,把 ‘repo start NAME .’ 中的 ‘.’ 换成你要改动过的项目路径。(NAME 是本地分支名字,自己取)
2.5.2 要提交补丁,总得打补丁吧,其实所谓的补丁就是指你对代码的改动,是不是只要我的改动逻辑正确就一定能通过审核呢,答案是否定的,提交的补丁除了需要功能逻辑正确以为,代码的格式还是很重要的,如果不注意很可能会被打回来,这里举个例子:android的代码规范里规定缩进不能用tab而是用4个空格。如果你对android的代码规范还不熟,就仔细研究下吧 : http://source.android.com/source/code-style.html#use-spaces-for-indentation
2.5.3 提交代码到本地的分支,这点和你平常使用git提交代码到本地分支基本是一样的,要注意的是提交信息怎么写,官方给了个模板,要按规范格式书写。
第一行不能超过60个字符,而且下一行要是一个空行。
描述要聚焦在你解决了什么问题,问题是如何解决的,如果你是加了个新的功能,可以另加一些描述新功能。
为了方便以后其他的贡献者的工作,请添加一些假设情况或者背景介绍。
-
Start with a one-line summary (60 characters max), followed by a blank line. This format is used by git and gerrit for various displays.
short description on first line more detailed description of your patch, which is likely to take up multiple lines.
-
The description should focus on what issue it solves, and how it solves it. The second part is somewhat optional when implementing new features, though desirable.
-
Include a brief note of any assumptions or background information that may be important when another contributor works on this feature next year.
2.5.4 提交你的补丁到Gerrit
- $ repo upload
还记不记得我们在~/.netrc 中写入了Gerrit的认证信息,提交的代码会跟提交者的Gerrit账户关联起来。
无图无真相,来看一个提交:
到这里,已经完成向Gerrit提交补丁的全部过程了,庆祝一下 ! 接下来就是等待社区的大牛们对你代码的审查了,审查并验证通过的代码才能被开源项目收录都仓库中!
这里再介绍一个小技巧,让你的代码尽快得到审核和验证,你可以自己邀请别人来帮你review和verify代码,review代码是不需要特殊权限的,你也可以帮别人review代码,能verify代码的人是掌握生杀大权的人,一般这项权利都由google的人来行使。
邀请别人帮你review可以加快你的patch被处理的速度。
以上是我向android贡献代码的个人经历,希望对android感兴趣的同学有所帮助,不对的地方还望指正,欢迎拍砖。