代码评审中的代码协同

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

做者 | 知忧
来源 | 阿里技术公众号

大神说：“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
生成的补丁文件的格式以下所示：

邮件头中的 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 < Email > ：一般由代码的贡献者（Author）和代码合入时的提交者（Committer）提供的签名。可由命令 git commit -s 、 git am -s 等命令自动添加。
Reported-by: User < Email > ：问题的报告者。
Helped-by: User < Email >：对提交有过帮助的人。
Reviewed-by: User < Email > ：评审者。
能够经过 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 聚集了阿里巴巴最新的代码托管、代码协同技术，但愿可以造福更多中国和世界的开发者。
原文连接本文为阿里云原创内容，未经容许不得转载。