产品使用文档/ 代码评审

代码评审介绍

代码评审是现代软件工程保证软件质量的重要工具和方法之一。一个工程师生产的代码交由另一位工程师或管理者检查, 不仅帮助发现潜在漏洞和不合理的设计,亦能在工程师文化与管理方面有所助益。

腾讯工蜂提供了代码评审的支持,首先,每一个发送到版本库中的提交,均能针对代码行发起评论,可以用来指出对代码的疑问和不足。 其次,在合并请求发起后,可在合并请求上附加评审流程,使分支的管理者能够控制必须经过评审的提交才能合入到分支中去。

什么时候会用到评审

在重要和敏感的项目(例如关键组件、接口、支付、交易等项目)中,由于变更的风险较高,往往要求每个提交都经过评审;而对于审核要求较低的项目,当关键参数、算法、接口结构改变等风险较高的变更发生时,亦应经过评审以减低风险。

查看评审

在左侧导航栏中选择代码评审,可以查看多个项目分配给自己的所有评审。

创建评审

基于代码提交后的评审

代码提交后的评审提供了基础版高级版基础版适合单分支开发的评审,评审规则继承该分支的评审设置。 高级版则适合跨分支和跨项目的评审,评审规则继承目标分支的评审设置。

基于代码提交后的评审新建之后不管有没有添加评委,新建即是代码评审。而新建合并请求添加评委之后算是一个代码评审,若没有添加评委则只是算合并请求,而不是代码评审。

要发起一个评审,可在创建合并请求时添加评审人。若合并请求已经创建,则可在右侧点击新增评审人

新建基础评审

代码提交后基础评审只能评审当前项目的某个分支。

  • 导航至项目-代码评审-创建代码评审-基础

  • 选择评审分支以及评审范围

    评审范围可以选择选中分支中需要评审的提交点,假设当前分支有a1、a2、a3、a4、a5、a6...... 等提交。总共需要选择两次,第一次选择的是源提交点,第二次选择的是目标提交点

    注意:此时比较是源提交点与目标提交点之间的文件,目前工蜂使用的三个点的对比,也就是git diff a...b, 不过由于现在是同一个分支,此时选择的两个提交点对比,底层其实也是直接对比这两个提交点的文件。

  • 输入标题等点击提交

    注意:表单中有其他选项设置,该设置表明发起人不可自己通过评审。 此设置当前页面不可修改,可以在项目设置的代码评审中或者保护分支设置里面修改

新建高级评审

代码提交后高级评审即能评审某一分支的提交,又可以评审跨分支和跨项目的提交。 高级评审提供源项目、源项目分支、源项目分支提交点和目标项目、目标项目分支、目标项目分支提交点的选择,同时源项目和目标项目都可以是当前项目fork的项目,非常灵活。

  • 导航至项目-代码评审-创建代码评审-高级

  • 选择评审分支以及评审范围

  • 输入标题等点击提交

    注意:其他选项表明

    • 发起人不可自己通过评审。 此设置当前页面不可修改,可以在项目设置的代码评审中或者保护分支设置里面修改。
    • 创建合并请求。 当源分支与目标分支的项目/分支不同,且提交点都是分支的第一个提交点时可勾选。

基于合并请求的评审

  • 创建合并请求的时候也可以添加评审人和必要评审人,创建成功后,这个合并请求就是一个代码评审,会出现在项目的评审列表中。

  • 创建合并请求的时候未添加评审人或者必要评审人,创建成功后,这个合并请求并不算是一个代码评审,不会出现在项目的评审列表中。

注意:编辑 MR 时不可以修改评审人规则,但可以添加评审人/必要评审人,以及删除评审人 。

评审状态

被添加的评审人,如有Necessary标识,表明改评审人被配置为必须存在并无法移除。 评审人最右侧的图标代表该评审人最近的有效意见, 黄色代表正在评审中,红色代表反对或打回修改,绿色钩号代表评审通过。

参与评审

单栏模式

直接进入变更页查看diff并评论即可。

经典模式

相对与单/双栏模式来讲,经典模式多了可以搜索文件、选择只看某两个提交点之间的diff、查看diff上下文等功能。

注意:假设当前评审a1、a2、a3、a4、a5、a6...... 等提交,在经典模式的选择提交按钮中可以选择评审中的若干提交点。 比如我第一次选择了a2提交,第二次选择了a5提交,则经典模式文件列表会出现a2、a3、a4、a5变更的文件文件。这对于想要缩小提交评审范围是一个非常方便的操作。

  • 切换经典模式

  • 选择提交,然后选择具体的文件进入查看diff

  • 查看上下文,评论diff

评审人设置

保护分支与非保护分支设置操作步骤一致,只有入口不一致。以下以非保护分支的设置为例。

导航至项目—设置—高级设置—代码评审,您可以在这里输入建议评审和必要的评审,然后点击保存变更。 还可以在这里设置评审人规则。

如果您要删除某位评审,则只需点击评委用户前的 × ,然后点击保存变更即可。

注意:

  • 高级设置中的代码评审设置是针对项目内所有非保护分支的,保护分支需要再具体的保护分支设置中逐个设置。
  • 此设置为创建评审时的默认设置,在实际创建评审时也可以按实际情况修改。

评审规则设置

默认的评审规则可以在具体的项目-项目设置-高级设置-代码评审中设置,也可以在创建合并请求/代码评审时根据实际情况修改。 目前评审人规则和必要评审人规则是评审人包含必要评审人,评审人和必要评审人按规则都要通过后,评审才能通过。

评审人规则

  • 单评审人同意即通过,即只需要一个评审人通过该mr就可以通过

  • 需要全部评审人同意,即需要所有的评审人通过该mr才能通过

  • 需要指定个数的评审人同意:即可以指定0-100个数的评审人通过,当通过评委数达到指定要求时,该合并请求才能通过。

必要评审人规则

  • 不需要必要评审人即可通过:即按照评审人规则通过后,不需要必要评审人通过,该合并请求就可以通过。

  • 需要至少一个必要评审人同意:即按照评审人规则通过后,至少需要一位必要评审人通过,该合并请求才可以通过。

  • 需要全部必要评审人同意:即按照评审人规则通过后,需要全部必要评审人同意,该合并请求才可以通过。

  • 需要指定个数的必要评审人同意:即按照评审人规则通过后,需要指定个数的必要评审人通过后,该合并请求就可以通过。