代码评审中的代码协同

 [[395093]]

大神说：“Show me the code”，于是就有了代码评审。

“Talk is cheap. Show me the code.”

——Linus Torvalds, founder of Linux and Git.

代码评审中同样存在着“Talk is cheap. Show me the code”，语言无力时，直接上代码吧。这就是我们今天要讨论的话题——代码评审中的代码协同。

一 基于邮件列表的代码评审

这是一种和代码仓库松耦合的代码评审模式，100%的代码都要经由一位或多位“仁慈的独裁者”(benevolent dictator)代码评审后才能合并入代码仓库。这种开发模式还需要开发者掌握一些命令行操作技巧以便完成代码在仓库和邮件列表之间的转换。采用这个模式的项目不多，不过 Linux、Git 开源社区就是按照这种模式运作的。

1 代码和邮件的相互转换

代码转换为电子邮件，要使用 git format-patch 命令。例如下面的命令将指定范围的代码提交(例如在 origin/master 之后的新提交)转换为电子邮件：

git format-patch origin/master..HEAD 

生成的补丁文件的格式如下所示：

From: Author Name <author@email> 
Subject: [PATCH] first line of commit message 
 
more commit message... 
--- 
 
 
diff --git ... 
<content of patch> 

• 邮件头中的 Subject: 字段是邮件标题，使用 [PATCH] 作为标题前缀，以提交说明的第一行作为标题内容。
• 更多的提交说明作为邮件内容，和邮件头之间用一个空行分隔开。
• 用分隔符 --- 作为提交说明的结束。
• 在分隔符 --- 和 diff --git 开始的补丁内容之间的文字被忽略。通常此处内容是提交的变更统计，开发者也可以在此处写入不宜列入提交说明中的附加说明。

git format-patch 命令有很多参数，要结合不同场景使用，例如：

• 一个特性由多个提交构成，分散在多个提交中的提交说明难以描述整个特性，可以使用 --cover-letter 参数，生成一封编号为 0000 的邮件，作为后续提交的摘要说明，便于评审者理解代码。
• 一个特性通常会多次迭代，就需要为每次迭代设置不同的版本。这就要用到 -v {num} 参数指定补丁的版本。版本将体现在邮件标题中，例如第二版本的补丁，邮件标题将使用 [PATCH v2] 作为前缀。
• 回复特定邮件，以便形成可追踪的邮件线索，使用参数 --in-reply-to="{Message-ID}"，为电子邮件生成相关的 In-Reply-To: 和 References: 头信息。
• 默认提交本身的作者、提交说明的签名区(trailer)提及的贡献者会自动添加为邮件的收件人。要添加更多参与者，可以使用 --to={email}、--cc={email} 参数。

将电子邮件转换为代码，则使用命令 git am [options...] mail... 。该命令会将邮件正确转换为 Git 仓库中的提交。

使用 git send-email 命令，将包含代码提交的邮件发送到邮件列表。

2 评审中的代码片段转换为提交

代码评审以邮件回复的方式完成。注意邮件回复都要求用纯文本格式，否则会被邮件服务器退信。

代码评审中发现小的文字错误，例如将 warning 写成了 waring，评审者可能做出如下简洁的回复：

s/waring/warning/ 

这种约定俗成的格式大概是源于 sed 命令实现文本替换的语法。

评审者有时候会在回复中贴上大段的代码补丁，为了使代码补丁和邮件上下文做出区分，会使用特殊的剪刀分隔符将邮件中的评论和代码补丁分隔开。

Subject: Re: whatever thread you're in 
 
Somebody else said: 
> blah blah blah 
 
I disagree. You should do it like this instead: 
 
-- >8 -- 
first line of commit message 
 
more commit message 
--- 
 
diff --git ... 

上面是 Peff(Jeff King)在邮件中给出的一个示范，看到其中的剪刀分隔符了么?剪刀分隔符由多个减号(穿孔的分割线)和一个剪刀符号组成至少8个字符的分隔符。可选的分隔符有：-- 8< -- 、-- >8 -- 、-- %< -- 或 --- >% --- 等。

使用 git am --scissors 命令，能够识别邮件中的剪刀分隔符，将邮件中的代码转换为提交。

3 为提交贡献者署名

Git的提交元信息中只包含两个署名信息，一个是提交的原始作者(Author)，一个是将提交合入仓库或者对提交做了修补的提交者(Committer)，而在提交评审过程中有过贡献的人往往不只两人，如何致敬贡献者呢?Git 社区的实践是在提交尾部(trailer)添加贡献者签名。贡献者签名由一个被动语态的关键字和贡献者ID组成，例如：

• Signed-off-by: User ：通常由代码的贡献者(Author)和代码合入时的提交者(Committer)提供的签名。可由命令 git commit -s 、 git am -s 等命令自动添加。
• Reported-by: User ：问题的报告者。
• Helped-by: User ：对提交有过帮助的人。
• Reviewed-by: User ：评审者。

可以通过 Git 项目仓库的提交历史，看到更多的签名示例。

4 使用 GitHub PR 实现代码到邮件的转换

一个名为 GitGitGadget 工具借助 GitHub 强大的扩展能力，通过向 gitgitgadget/git 仓库发送 pull request，实现提交到邮件的转换，并发送到 Git 项目的邮件列表中。使用 GitGitGadget 参与 Git 社区代码贡献详见。

二 GitHub 代码评审中的协同

GitHub 使用 pull request 进行代码评审，评论中的代码块儿也可以转换为提交。

1 代码评论中嵌入代码块

下图中，点击评论工具栏第一个按钮，可以在评论中嵌入代码块：

2 评论中代码块转换为提交

对 pull request 的源仓库具有写权限的用户，可以将评审中的代码库转换为提交，如下图所示：

于是代码评审中会增加一个新的修正提交。

GitHub 的这个功能对于代码评审中发现的一些小问题，还是非常方便的。但是大的修改就无能为力了。

3 线下评审

对于功能复杂的 pull request，在线上浏览代码不方便，也不能线上调试代码，这时线下获取并浏览代码，就非常有必要了。

GitHub 的代码仓库中为每一个代码评审设置了特殊的关联引用：

• refs/pull/{ID}/head ：关联 pull request 的源提交。
• refs/pull/{ID}/merge ：对于没有冲突的 pull request，这个引用指向一个成功的合并提交。

代码评审者使用如下命令可以获取 pull request (例如编号为 123 的 PR)指向的提交：

git fetch origin refs/pull/123/head 
 
git switch -d FETCH_HEAD 

评审者可以线下调试 pull request 指向的代码，但是对代码做出的本地修改，没有办法直接更新到线上的代码评审中。

阿里巴巴的云效Codeup，支持线下到线上的代码协同。

三 云效Codeup代码评审中的协同

无论是 GitHub 还是 Gitlab，开发者创建代码评审首先需要将代码推送到线上独立的分支中(无论是在线上的派生仓库，还是目标仓库)，然后再通过网页选择来源仓库、分支及目标仓库、分支，创建代码评审。

GitHub 和 Gitlab 这种代码评审方式，或者要引入冗余的派生仓库，或者需要为开发者赋予在仓库中的写入权限，并容易引发杂乱的分支管理。

1 适合主干开发的无分支创建代码评审

云效 Codeup 可以通过 git push 命令在客户端直接创建代码评审，无需创建派生仓库或者在仓库中创建特性分支。例如在客户端执行如下命令：

git push origin HEAD:refs/for/master/topic1 

该命令会在服务端创建新的代码评审，或者如果已经存在相同用户、相同命令创建的代码评审则会更新评审中的提交。

建议安装我们开源的 git-repo 工具，则可以用更简单的命令行，实现从客户端创建/更新代码评审。

git pr 

2 线下评审，线上协同

和 GitHub 类似，云效 Codeup 创建的代码评审都有一个特殊引用相关联，格式为：refs/merge-requests/{ID}/head。

代码评审者可以使用 git fetch 命令获取特定的代码评审(以编号123为例)指向的代码，进行线下代码评审。

git fetch origin refs/merge-requests/123/head 
git switch -d FETCH_HEAD 

如果安装了 git-repo，可以使用下面更为简洁的命令：

git download 123 

代码评审者除了可以在本地仓库中浏览、调试代码，还可以更新代码、创建提交，然后将本地新增提交更新到线上的代码评审中。命令示例如下：

git pr -c 123 

在云效 Codeup，开发者和评审者可以基于代码评审进行更为流畅的代码协同。

3 Git proc-receive 挂钩

上述“线下评审、线上协同”功能的核心是 Git 的 proc-receive 挂钩和 report-status-v2 新能力。这一功能由阿里巴巴贡献给 Git 社区，并在 Git 2.29.0 发布。

云效 Codeup 汇集了阿里巴巴最新的代码托管、代码协同技术，希望能够造福更多中国和世界的开发者。