Gerrit 用户指南
关于Gerrit
Gerrit,一种开放源代码的代码审查软件,使用网页界面。利用网页浏览器,同一个团队的程序员,可以相互审阅彼此修改后的代码,决定是否能够提交,退回或是继续修改。它使用版本控制系统Git作为底层。
本书作为一本指导用户使用Gerrit的简易手册,将主要介绍Gerrit的工作流程和如何利用Gerrit进行代码审查。
注:在阅读一下内容前,默认用户具备熟练使用Git的能力。想了解Git参见Git使用手册
定位
理论上Git虽然是一个分布式版本管理系统,不需要中心代码库就能相互同步数据。而在实际的操作过程中,为了方便一个团队的多名开发人员通常需要指定一个确定的代码库用于提交和相互同步代码。所以我们开发团队代码管理一般使用如下结构:
在引入Gerrit代码审核机制后,我们的代码提交和同步的方式发生了变化:
工作流程
首先贡献者的代码通过 git 命令(或 repo 封装)推送到 Gerrit 管理下的 Git 版本库,推送的提交转化为一个一个的代码审核任务,审核任务可以通过 refs\/changes\/<change-id>下的引用访问到。代码审核者可以通过 Web 界面查看审核任务、代码变更,通过 Web 界面做出通过代码审核或者打回等决定。测试者也可以通过 refs\/changes\/<change-id>引用获取(fetch)修订对其进行测试,如果测试通过就可以将该评审任务设置为校验通过(verified)。最后经过了审核和校验的修订可以通过 Gerrit 界面中提交动作合并到版本库对应的分支中。 在 Android 项目的网站的代码贡献流程图更为详细的介绍了 Gerrit 代码审核服务器的工作流程。
相信在阅读完上面Gerrit的工作流程图后,大家对Gerrit有个大致的了解,接下来我们将进入实际的操作步骤,细致讲解如何利用Git完成上诉流程。我们已经准备了一个叫Gerrit-Base的测试项目供大家练手。
克隆代码仓库
进行代码修改、提交审查,显然第一步是要从远程代码库中克隆一份代码。我们的Gerrit服务提供了HTTP和SSH两种服务供大家从远程服务器获取代码,获取方式可在项目基本信息页面查看。
为个人账户安全选择SSH协议获取代码。当然安全既有安全的代价,使用SSH协议需要配置本机密钥。
$ git clone ssh://[username]@[hostname]:[port]/Gerrit-Base
Cloning into Gerrit-Base...
remote: Counting objects: 2, done
remote: Finding sources: 100% (2/2)
remote: Total 2 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (2/2), done.
Checking connectivity... done.
创建审查
本步骤操作前默认已完成了创建、删除或修改本地文件,并将修改添加、提交到本地版本库。
$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Untracked files:
(use "git add <file>..." to include in what will be committed)
hello_gerrit
hello_gerrit.c
nothing added to commit but untracked files present (use "git add" to track)
$ git add .
$ git commit -m "this is a new change"
$ git push origin HEAD:refs/for/master
注:在初次克隆代码时需要从服务器下载hook脚本用于每次审查自动生成change-id。
$ scp -p -P [port] [username]@[hostname]:hooks/commit-msg Gerrit-Base/.git/hooks/
$ git commit --amend
$ git push origin HEAD:refs/for/master
创建审核后,服务器目前的状态为:
审查代码
当提交修改成功后,默认情况下项目的所有者、管理员能够指定代码的审核人。指定审核人后,Gerrit会给审核人发送邮件提醒有审核任务。
审核代码的流程:
- 浏览代码增量,并给出注释;
- 浏览完成所有代码,并给出综合评价和评分(-2, -1, 0, 1, 2)。
多人评审后当总分>=2时,表示审核通过,进入下一步的代码验证流程;否则需要提交者返工修改。
图1. 添加审核者
图2. 查看代码增量
图3. 添加注释
图4. 总评和评分
返工修改
根据上面Gerrit流程图,当代码审核、确认未通过或合并的过程中出现冲突,这个时候就需要返工修改后再提交。
返工流程有三步:
- 获取未通过的代码到本地工作目录;
- 修改代码;
- 再提交审核。
Git命令实现为:
$ git fetch http://[username]@[hostname]/Gerrit-Base refs/changes/35/35/1
$ git checkout FETCH_HEAD
... // 修改代码
$ git add <path-of-reworked-file>
// amend commit
$ git commit --amend
// push patch set
$ git push origin HEAD:refs/for/master
修改后的提交,change-id不会发生变化,而仅仅是patch-id加1。因此对返工后的修改引用为“refs\/changes\/35\/35\/2”。
验证修改
新提交的修改,如果已经通过代码审核,下一步流程则是代码验证。验证之前需要代码测试人员先将修改获取到本地,然后对代码进行测试。代码测试后,则投票对本次修改做出评价。
提交修改
当代码成功通过Review和Verified后,此时这段修改后的代码片段就可以合并到主分支里面去了。