• 帮助文档

# 代码评审介绍

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

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

# 什么时候会用到评审

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

# 查看评审

在左侧导航栏中选择代码评审，可以查看多个项目中有关自己的评审。

# 创建评审

# 基于代码提交后的评审

  • 代码提交后的评审提供了基础版和高级版，基础版适合单分支开发的评审，高级版则适合跨分支和跨项目的评审。
  • 基础评审规则继承该分支的评审设置，高级评审规则继承目标分支的评审设置。
  • 基于代码提交后的评审新建之后不管有没有添加评委，新建即是代码评审。而新建合并请求添加评委之后算是一个代码评审，若没有添加评委则只是算合并请求，而不是代码评审。
# 新建基础评审

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

  1. 入口：登录工蜂 Git-找到我的项目-->代码评审-->创建代码评审-->基础

re_add

  1. 选择评审分支以及评审范围 评审范围可以选择选中分支中需要评审的提交点，假设当前分支有 a1、a2、a3、a4、a5、a6...... 等提交。 总共需要选择两次，第一次选择的是源提交点，第二次选择的是目标提交点 （此时比较是源提交点与目标提交点之间的文件，目前工蜂使用的三个点的对比，也就是 git diff a...b, 不过由于现在是同一个分支，此时选择的两个提交点对比，底层其实也是直接对比这两个提交点的文件。

  2. 按照页面提示输入标题、描述等其他信息。然后点击提交

# 新建高级评审

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

  1. 入口：登录工蜂 Git-找到我的项目-->代码评审-->创建代码评审-->高级模式

    image.png

  2. 选择评审分支以及评审范围

    image.png

  3. 按照页面提示输入标题、描述等其他信息。然后点击提交 。

注意：当源分支与目标分支的项目/分支不同，且提交点都是分支的第一个提交点时可勾选创建合并请求

# 基于合并请求的评审

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

# 参与评审

# 评审状态

评审人最右侧的图标代表该评审人最近的有效意见，黄色代表正在评审中，红色代表反对或打回修改，绿色钩号代表评审通过。

被添加的评审人，如有蓝色 V标识，代表是必要评审人这些必要评审人被配置为只有 master 及以上权限的用户才能移除他们。

# 查看 diff

# 单/双栏模式

在 MR 详情页可选择单/双栏模式查看 diff image.png

# 全屏评审模式

相对与单/双栏模式来讲，全屏评审模式更方便评审人去评审代码

  1. 从 MR 详情页进入全屏评审模式 image.png
  2. 在全屏评审模式下查看 diff image.png

# 发表评论

# 对 diff 行发表评论

评委在查看 diff 时，可以针对某行有疑问的代码进行评论。评论时如需添加标签可以参考标签的应用 image.png

# 划词评论

也可以对多行代码或者某几个字符进行评论 image.png

# 代码建议

作为评委，可以在直接在走查评论中使用 Markdown 语法提出代码修改建议，代码建议会以 diff 的形式渲染在评审框内。 image.png

对于轻量级的修改建议，作者能够更便捷地在页面上实现一键修改。若接受评论中的代码建议，可在页面上直接点击采纳建议（需具有源分支 push 权限）一键提交代码，在源分支上生成一个新的提交点。 image.png

# 评审设置

评审设置均是以合并请求的目标分支设置为准。工蜂评审规则需要根据目标分支的属性不同，在非保护分支规则或保护分支规则组中分别配置
保护分支规则：应用于规则组下的保护分支（导航：项目—设置—分支规则—保护分支规则组）
非保护分支规则：控制所有非保护分支（导航：项目—设置—分支规则—非保护分支评审规则）

image.png

# 合并请求规则设置

以下案例均为非保护分支的评审设置，保护分支与非保护分支设置仅入口不同，操作步骤一致。

# 允许合并操作设置

设置 MR 只允许合并负责人或者具有 Developer 及以上权限的用户去操作合并该 MR image.png

# 合并规则设置

image.png

  • 规则 1：勾选后，如果有包含的 commit 还没有评审通过时，就阻止源分支到目标分支差异点在目标分支上的推送；
  • 规则 2：勾选后，合并请求必须邀请评委或者文件负责人来评审并通过后，才能合并这个合并请求
  • 规则 3：勾选后，合并请求必须配置且通过流水线检查，才可合并。（注：流水线未配置或因 hook 延迟未触发，也会卡住 MR）
  • 规则 4：勾选后，源分支上有新的提交后，评审状态将有变化
    • 规则 4.1：一旦源分支上有新的提交，已同意的评审人状态将全部重置为需评审状态
    • 规则 4.2：当整单的评审状态为通过，一旦源分支有新的提交，已同意的评审人状态将全部重置为需评审状态
    • 规则 4.3：仅针对开启OWNERS机制的单，一旦源分支上有新的提交，如果被修改的文件所对应的 owners 已同意，则将他们的意见重置为需评审。同时，如果单里有除 owners 角色以外的评审人，他们的已同意也会被重置为需评审

附：规则 2、3 生效效果

image.png

# 合并方式设置

设置 MR 的合并方式，以及默认的合并请求方式。其中合并方式是多选，但是默认的合并请求方式只能是单选 image.png

# 合并请求模板设置

设置 MR 的描述模板，默认值为该 MR 的最新提交点的提交描述 image.png

# 合并负责人设置

可以将某一个用户或者MR 的创建者设置为该 MR 的合并负责人，或者不设置默认的合并负责人 image.png

# 推送规则

勾选后，在对应的分支上进行提交后会根据预置好的评审规则自动创建一个代码评审 image.png

# 评审规则设置

  • 规则 1：勾选后，合并请求/代码评审的创建者不能通过自己创建的合并请求/代码评审
  • 规则 2：勾选后，创建评审时，项目权限在 master 以下的成员不能修改预置的评审规则，master 及以上权限的成员可以修改评审规则
  • 规则 3：勾选后，用户在 diff 的首评论时必须加上标签
  • 规则 4：勾选后，合并请求/代码评审中所有的未解决评论需要都解决后才能通过评审
  • 规则 5：勾选后，合并请求/代码评审中的文件如果匹配上 OWNERS 文件，则需要对应的文件负责人通过后才能通过该合并请求/代码评审中

image.png

# 评审人规则设置

您可以单击规则中下拉框选择所需要的评审人规则，以及是否启用持证评审 image.png

# 配置评审时无需关注的文件

预配置评审时无需关注的文件，如：自动生成文件、测试文件等。在工蜂页面上创建 CR 时，被命中的文件将自动置为“非重点文件”而默认折起。
注：文件路径支持通配符语法，可参考 git 的PATTERN FORMAT image.png

在 CR 变更列表、文件树（仅评审视图）中，这类无需关注的文件会被归为“其他文件”类别，默认被折叠。
注：配置有文件负责人的文件，无法被折叠，将默认展示 image.png

# 默认评审人设置

您可以在这里增加或删除默认配置的评审人和必要评审人，以及配置路径评委规则，然后点击保存变更。 image.png 路径评审规则：*.js review reviewer=username1,username2

这个写法意思是：匹配到后缀为 js 的文件有改动时，username1,username2 本不是评委的，也会加到这个 mr 的评委中。

文件路径支持通配符语法，可参考 git 的PATTERN FORMAT

Ps: 创建评审时，当评审的文件路径匹配中了路径评委规则的配置的时候，会自动把设置的 reviewer 填充到评审人（可删除）选项中，同时把设置的 necessary_reviewer 填充到必要评审人（不可删除）选项中;

# 设置主干分支禁止提交

  1. 假设主干分支为 master 分支
  2. 进入项目的 设置–分支规则 - 保护分支规则组，点击新增保护分支，在分支下拉框中选择 master，并将允许推送代码设置为 任何人都不允许
  3. 点击确认。 image.png
  4. 设置为保护分支后，也可以进入该分支所在的规则组，将允许推送设置为任何人都不允许，然后点击最下面的保存变更。 image.png

注意：保护分支也不可以强制 push 哦

# 设置主干分支的合并请求必须经过评审

  1. 进入刚刚的保护分支规则组页面，找到 master 分支所在的规则组，并点击 编辑规则组 按钮

image.png

  1. 找到合并请求规则，并勾选合并请求必须通过代码评审才可以合并

    image.png

  2. 点击保存变更

# 单文件评审

# 文件负责人

在工蜂 Git 中，您可以通过在默认分支上配置.code.yml文件来达到需要文件负责人来评审对应文件的目的。默认分支配置后，对该项目的所有分支生效。

文件格式

file :
    #通过正则来匹配对应的文件
  - path: ".*"
    # 必填项，文件负责人
    owners :  [""]
    # 必填项，文件负责人通过规则可选值 -1,0,大于等于1的整数;
    # -1,表示需所有owner审批；
    # 0，表示该文件无需任意一个owner审批;
    # 1+,用大于等于1的整数，表示需要相应整数个的owner审批该路径，比如2，标识需要任意两个owners审批
    owner_rule: 1

当用户被匹配到文件规则成为文件负责人时，他可以在 MR 的页面中看到自己负责人的文件以及通过规则： image.png

# 文件已阅

可以合并请求对您已经审阅过的文件进行标记。勾选已阅文件，默认将文件折叠起来。且有进度条显示文件阅读进度。 image.png

# 文件置顶

在合并请求中还可以将您认为重要的文件进行置顶，方便阅读。还可以设置只看置顶的文件

image.png

# 文件选项

工蜂也提供了四个选项辅助评委更便捷的走查代码 image.png

lastUpdate: 9/27/2024, 4:00:26 PM

← 项目设置 →