Gerrit Code Review 简明教程

Warning

  1. 下面代码中涉及的 origin 是 git clone 下来默认远端仓库的名字。

  2. 下面代码中涉及到的分支名也不要盲目拷贝, 根据你要想要提交代码的远端分支，进行相应的修改。
Note

此文档默认使用者具备熟练使用 Git 的能力，Git 教程请参考： http://learngitbranching.js.org/。
Note
更多资料

此文档是为 Gerrit 初学者定制的，Gerrit 高级功能以及细节建议参考官方文档 [1] [2] [3]。

Slides

  1. https://blog.simplypatrick.com/html/gerrit-best-practices.html

  2. http://wincent.github.io/gerrit-best-practices-tech-talk/assets/fallback/index.html

1. 准备工作

1.1. 安装并配置 Kerberos

Kerberos 是一种由 MIT 开发的验证协议，我们使用 Kerberos 协议来认证开发人员的身份。 使用 Gerrit Code Review 系统拉取或提交代码是将使用 Kerberos 协议进行认证。

Tip

修改密码请使用 kpasswd 命令。

安装配置成功后，可请执行使用 kinit [email protected] 认证并获取票据。

Note
 kinit 产生的票据是有有效期的，通常设置为 24 小时。

1.2. 配置 SSH 及 Git 客户端

  1. 在 ~/.ssh/config 中添加如下配置：

    Host git.7v1.net
    Port 29418
    GSSAPIAuthentication yes
    GSSAPIDelegateCredentials no
    PreferredAuthentications gssapi-with-mic
    Compression yes

  2. 在 ~/.gitconfig 中添加在日常开发及代码评审过程中常用 alias 命令：

    [alias]
    new = "!f() { git fetch && git checkout -b sandbox/`whoami`/`date +%m-%d`/${2:-`date +%H-%M`} origin/${1:-master}; }; f"
    rvm = "!f() { git push origin HEAD:refs/for/master%${1}; }; f"
    rv = "!f() { git push origin HEAD:refs/for/${1:-master}%${2}; }; f"
    fp = "!f() { git fetch origin refs/changes/$(printf "%02d" $(expr ${1} % 100))/${1}/${2:-1} && git checkout FETCH_HEAD;}; f"
    cin = commit --amend --no-edit
    delbranch = "!f() {git branch | grep sandbox | xargs git branch -D; }; f"

1.3. 拉取代码

拉取代码有多种方式 [4]，我们只提倡使用基于 Kerberos 认证的 ssh 协议拉代码，命令如下：

git clone ssh://git.7v1.net:29418/your-project

其他方式均不推荐。

1.4. 配置自动生成 Change-Id

一次 Code Review 的 Change 可能需要多轮 Patchset 的迭代, 因此需要使用 Change-Id [5] 来作为 Change 的标识。Gerrit 提供了「commit-msg hook」在 git commit 时自动生成 Change-Id。

Change-Id 示例
commit d8c5feab2b1a7f002de2f3b232fa47cc3fd45435
Author: Pengda Su <[email protected]>
Date:   Wed Jun 1 19:20:13 2011 +0800

    factory test: enable first time boot factory test mode.

    Change-Id: Ifd07e0068aca097350e75d445dd26c603a65997f

具体步骤如下

  1. 首先下载 commit-msg 到 ${GIT_TEMPLATE_DIR} 目录（例如：~/.git-tmpl），并设置 gitconfig 的 init.templateDir。

    GIT_TEMPLATE_DIR=~/.git-tmpl
if [ ! -d ${GIT_TEMPLATE_DIR}/hooks ]; then
    mkdir -p ${GIT_TEMPLATE_DIR}/hooks
fi

curl -kLo ${GIT_TEMPLATE_DIR}/hooks/commit-msg https://git.7v1.net/tools/hooks/commit-msg
chmod +x ${GIT_TEMPLATE_DIR}/hooks/commit-msg

git config --global init.templateDir ${GIT_TEMPLATE_DIR}

  2. 对这之后新的 git clone 的仓库，commit-msg 机制自动生效；对之前的仓库，可在仓库的根目录下执行 git init 或者下面命令。

    COMMIT_MSG=`git rev-parse --git-dir`/hooks/commit-msg
curl -kLo ${COMMIT_MSG} https://git.7v1.net/tools/hooks/commit-msg
chmod +x ${COMMIT_MSG}
Warning
 git revert 不会自动生成 Change-Id, 可使用 git --amend --no-edit 或 alias 命令 git cin 来生成 Change-Id。

2. 开发及评审

2.1. 主干（master 分支）开发模式

  1. 执行命令下面的命令（或者执行 alias 命令 git new），它会把远端的 master 拉下来并基于 origin/master 创建一个新分支，如：sandbox/lifei/05-04/02-28。

    git fetch
git checkout -b sandbox/`whoami`/`date +%m-%d`/`date +%H-%M` origin/master

    这样可以保证每次修改都是基于远端分支的最新修改，避开本地分支中含有未合并 commit 的坑。

    Note

    1. 上例中 sandbox/ 系列分支仅为示例，表示为任意的本地临时分支，可按照自己的喜好进行调整。

    2. 本地的临时分支会不断积累，可执行命令 git branch | grep sandbox | xargs git branch -D 或者 alias 命令 git delbranch 来批量删除。

  2. 根据需求进行开发，构建并测试你的代码。

  3. 完成后，执行 git commit 将你的修改提交。

  4. 执行下面的命令（或者 alias 命令 git rvm r=xxx,cc=yyy,topic=zzz），将你的修改提交到 Gerrit Code Review 系统中 [6]。

    git push origin HEAD:refs/for/master%r=xxx,cc=yyy,topic=zzz
    Note
    		 请将上文中「xxx」、「yyy」替换为适当对象的 Kerberos 账号，「zzz」替换为你本次提交的主题（r 表示 reviewer，cc 表示抄送，r 和 cc 均可出现多次，topic 表示主题，均可省略）。

  5. 提交成功后会得到如下提示，里面有一个 URL，在浏览器中打开这个 URL 即可进行代码评审[7]。

    Counting objects: 6, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (6/6), done.
Writing objects: 100% (6/6), 1.07 KiB | 0 bytes/s, done.
Total 6 (delta 4), reused 0 (delta 0)
remote: Resolving deltas: 100% (4/4)
remote: Processing changes: new: 1, refs: 1, done
remote:
remote: New Changes:
remote:   https://git.7v1.net/262547 fix: 修正接收消息的逻辑
remote:

  6. 请你的指定的 reviewer 对你的 Change 进行评审。一般标准如下：

    1. 如果认为方案有问题，没必要做此修改，选 -2；

    2. 如果认为代码有缺陷，不能提交（Submit），选 -1；

    3. 如果认为代码没问题，但自己对代码不是很有把握，得由其他人来决定代码是否可提交，选 1；

    4. 如果认为代码没问题，可以提交，选 2。

    Tip
    操作示例

    • 直接点击「Code-Review+2」（蓝色箭头）

    • 点击「Reply…​」按钮 ⇒ 「Code-Review」分数单选框 ⇒ 「Post」按钮（红色箭头）。

    操作截图

2.2. 二次评审

有时候你的代码中可能包含某些错误，别人帮你 review 出来了，这时就需要进行二次评审。 二次评审很常见，过程也很简单，基本步骤如下[8]：

  1. 保存或清理你之前的工作，保持本地仓库干净，如 git stash 等命令。

  2. 切换到被评审后需要修改的版本。

    1. 方法一：点击 Change 详情页右上角「Download」下拉箭头拷贝下载命令执行。

    2. 方法二：使用命令手动下载。

      1. 找到需要二次评审的 Change Number，如：一个 Change 的 URL 为 https://git.7v1.net/251126，那么它的 Change Number 就是 251126，下称「CHANGE」。

      2. 确定要基于哪个 Patchset 进行修改，可在 https://git.7v1.net 界面中拿到（Change 详情页的右上角，「Patch Sets」下拉箭头），下面称「PATCHSET」。

        patchset.png

      3. 执行下面的命令（或者执行 alias 命令 git fp {CHANGE} {PATCHSET}），将要修改的 Patchset 拉到本地。

        git fetch origin refs/changes/{CHANGE 的最后两位}/{CHANGE}/{PATCHSET}
# 如 251126 号 Change 第 2 个 Patchset
# git fetch origin refs/changes/26/251126/2
git checkout FETCH_HEAD

        • 请不要盲目照抄上述命令，「{}」的内容请按照规则进行替换。

  3. 根据评审建议进行修改，构建并测试你的代码。

  4. 完成后，执行命令 git commit --amend --no-edit（或者执行 alias 命令 git cin）进行提交。

    • 如果是本次提交的 commit message 需要修改，请使用 git commit --amend 命令提交。

  5. 执行下面的命令（或者 alias 命令 git rv），将你的修改提交到 Gerrit Code Review 系统中。邀请你的评审者进行二次评审。

    git push origin HEAD:refs/for/master
    Tip
    		 二次评审不需要再次指定 reviewer 等信息。

2.3. 分支开发

有的需求比较大或者需要前后端多人配合，这时候就需要进行分支开发。

Note
 这里以 feature/yigexuqiu 为例。

  1. 首先基于 origin/master 分支新建一个 feature/yigexuqiu 分支；

    • 可以在 Web 界面上新建分支；

      create branch.png

    • 也可以执行命令：git fetch && git push origin origin/master:feature/yigexuqiu；

  2. 执行下面的命令（或者执行 alias 命令 git new feature/yigexuqiu），切换到临时分支；

    git fetch
git checkout -b sandbox/`whoami`/`date +%m-%d`/`date +%H-%M` origin/feature/yigexuqiu

  3. 根据需求进行开发，构建并测试你的代码。

  4. 完成后，执行 git commit 将你的修改提交。

  5. 执行下面的命令（或者执行 alias 命令 git rv feature/yigexuqiu r=xxx,cc=yyy,topic=zzz），将你的修改提交到 Gerrit Code Review 系统中。

    git push origin HEAD:refs/for/feature/yigexuqiu%r=xxx,cc=yyy,topic=zzz

    • 相关事项均同主干开发模式

  6. 二次评审时，将命令修改为下面的命令或者将 alias 命令 git rv 改成 git rv feature/yigexuqiu 即可。

    git push origin HEAD:refs/for/feature/yigexuqiu
    Tip
    		 二次评审不需要再次指定 reviewer 等信息。

  7. 合并代码到 master 分支。

    • 受项目工作流限制，部分仓库普通研发工程师可能没有 push 以及提交 merge 节点的权限，本操作仅能由项目 owner 完成；

    • 命令 git fetch && git merge origin/master && git push origin HEAD:master

  8. 合并完成后删除相关的远程分支：git push origin :feature/yigexuqiu。

2.4. 提交代码到 master 分支

在 Gerrit Code Review 系统的 Web 界面上点击 Submit 即可将代码合并到主干。

results matching ""

    No results matching ""