本主题解释如何设置和运行预提交代码审查流程,在此流程中,开发人员在提交代码到源代码控制 之前 提交代码以供审查。每次开发人员需要评审他们的代码时,他或她都会运行代码评审测试配置。此测试配置检测代码更改,并准备对其进行检查。
本章包含:
配置概要
配置预提交代码审查需要:
- 在所有团队安装上设置适当的首选项,如 常规代码审查配置中所述。
- 在一台机器上配置代码评审测试配置,并在整个团队中共享它,如下所述
为预提交代码评审配置测试配置
代码评审配置检测代码更改,并准备对其进行检查。我们建议配置一个测试配置,并使用团队服务器在整个团队中共享它。这简化了配置和更新。
你可以创建一个专门用于代码评审的测试配置,或者拥有一个检查代码评审以及执行其他分析的测试配置。
若要配置检测代码更改的测试配置,并准备对其进行检查:
- 通过选择 Parasoft> Test Configurations 或选择 Test Using 工具栏按钮上下拉菜单中的 Test Configurations ,打开测试配置对话框。
- 复制现有的测试配置(例如,Built-in> Code Review> Pre-Commit) 或创建一个新的测试配置。
- 在 Scope 选项卡中,选择 Test only files added or modified locally。
- 同样在 Scope 选项卡中,查看 File Filters> Path 选项设置,并根据需求对它们进行调整。
- 如果报告首选项尚未设置为使用唯一的会话标记进行代码检查扫描,请进入 Common 选项卡,启用 Override Session Tag,然后选择其中一个预配置的标识符或指定自己的标识符。这个标签将被分配给所有源于这个测试配置的代码评审。
- 为了确保正确的代码评审报告,你必须为代码评审扫描配置一个会话标记,并在 DTP 中使用该会话标记,以指定哪些代码评审与特定的项目相关联。
- 在 Code Review 选项卡顶部:
- 选择 Enable Code Review Scanner。
- 如果希望报表包含所有可用团队扫描器的代码评审结果,请启用 Generate comprehensive report (includes all scanners)。此选项通常不用于预提交代码检查。如果未启用此功能,则报告将只包含指定会话标记的结果。
- 如果想要评审任务在运行此测试配置后自动“发布”(上传),请启用 Auto publish reviews 预提交代码检查推荐这样做。
- 在 Generate tasks with priority 框中,指明了应分配给使用此测试配置创建的所有代码评审任务的优先级。
- (可选)如果希望自动分配审查,请使用 Authors、 Reviewers、 Monitors和 Filters 选项卡来定义希望分配代码评审的方式。评审人员和监视器可以分配给特定的作者,或者分配给特定的项目区域。如果此处没有指定选项,则每个作者需要为每个提交的评审选择适当的审阅人。
- 在 Authors 选项卡中,定义正在编写需要评审的代码的开发人员列表。对于每个作者,指定一个作者名称和一个源代码控制登录(如果作者的源代码控制登录与作者的名称不同)。
- 作者列表可以包括所有开发人员,也可以只包括初级开发人员。
- 如果没有在此选项卡中定义提交代码更改的开发人员,那么更改将被标记为来自“未定义的作者”。
- 如果不希望定义每个开发人员,那么可以 1) 启用 Filter 选项卡的 Accept all (also undefined) authors for reviewed paths,2) 然后使用 Reviewers 选项卡来定义哪些评审人员应该评审代码的不同部分。
- 在 Reviewers 和 Monitors 选项卡中,指定希望每个审阅者或监视器涵盖哪些作者和/或项目领域。
- 评审员检查、评论和批准代码更改。监察员监督整个过程,以确保修订被及时审查和纠正。它们不需要执行任何评审,但是可以向修订或评审添加注释。这个角色是可选的。
- 路径在逻辑(工作控件)路径规范中定义。允许使用通配符。有关详细信息和示例,请参阅下面的“Filter Tips and Examples”框。
- 你可以定义审阅者和监视器,而不需要将它们映射到任何特定的路径或作者。这些用户不会被自动分配到任何包中,但是他们将被包含在报告中,并且作者将能够在“代码评审助手”对话框中选择他们。
- 这些选项卡使用 OR 逻辑(不是 AND 逻辑)。换句话说,你定义了审阅者(或监视器)的名称,然后定义了希望该人员审阅(或监视器)的作者和审阅路径。然后,如果新代码来自指定的作者或(OR)指定的路径,那么它将被分配给指定的审阅者或监视器。
- 在 Authors 选项卡中,定义正在编写需要评审的代码的开发人员列表。对于每个作者,指定一个作者名称和一个源代码控制登录(如果作者的源代码控制登录与作者的名称不同)。
- (可选)在 Code Review> Filters 选项卡中,如果需要,修改以下选项:
- 忽略抑制块中的更改:如果希望代码评审扫描忽略“codereview-begin-suppress”和“codereview-end-suppress”标记之间发生的所有差异,请启用此选项。这些标记与用于防止比较编辑器在特定代码块中显示差异的标记相同(关于更多详情,请查阅 Hiding Differences for Specific Pieces of Code )。
- 差异:如果你希望代码评审扫描忽略与特定模式匹配的所有当前源与先前源之间的差异,请在这里指定适当的正则表达式。例如,你可以使用它来防止自动生成的注释中的任何差异被标记为需要代码检查。
- Post to Pre-Commit matching: 包含用于混合提交前和提交后代码审查流程的选项,在此过程中,开发人员需要提交代码以便在检查之前进行审查,但也使用提交后扫描来验证是否遵循了此流程。
Post to Pre-Commit matching: 如果你希望提交后扫描忽略与特定提交前扫描与提交后扫描之间的差异,请在这里指定适当的正则表达式。例如,你可以使用它来防止签入时自动生成的 CVS 数据头中的差异被标记为提交后代码检查。关于更多详情,请查阅 Running Post-Commit Scans with a Pre-Commit 。
- Pre-commit search range in days: 如果你想自定义用于确定哪些预提交任务对应于评审后任务的时间框架,请更改此设置。 关于更多详情,请查阅 Running Post-Commit Scans with a Pre-Commit 。
- Accept all (also undefined) authors for reviewed path: 如果不希望定义每个开发人员,那么可以 1) 启用 Accept all (also undefined) authors for reviewed paths,2) 然后使用 Reviewers 选项卡来定义哪些评审人员应该评审代码的不同部分。
- 单击 Apply ,提交新的测试配置。
- 通过右键单击该选项,然后从快捷菜单选择 Upload to Team Server 以共享测试配置。
提交代码审查 - 互动桌面执行
每个开发人员在完成新的/修改过的代码后,应执行以下步骤,以备检讨:
- 在项目树中,选择表示要查看的更改的节点。
- 运行指定的代码评审测试配置。这应该在团队类别中。
- 如果启用了代码评审首选项面板中的 Show user assistant during scanner run 选项(强烈推荐),那么 SOAtest 将显示代码评审助手。
你可以使用该对话框来:- 指明代码与什么任务相关(然后此代码评审将与此任务相关联)。你可以从任务列表中选择现有任务。或者,你可以通过输入新任务名称来创建新任务。此信息用于确定你是否仍在处理现有任务,或者是否已经启动了新的任务。你的更改将在准备好的代码评审包中按任务分组。
- 当你提交一个新任务供评审时,为提交的修订指定一个特定的评审人员或监视器。这允许你覆盖默认的审阅人/监视器分配,或者指定一个尚未分配的审阅人。
- 提供审阅者或监视关于当前更改的附加信息。
- 指明评审的优先次序。
- 输入与所选文件相关的注释。这些注释将在“常规任务”中捕获。 这是添加关于此审查包的常规注释的一个机会。
- 如果你的代码评审测试配置没有启用 Auto publish reviews ,那么将结果上传至团队服务器,如下所示:
- 测试完成后,单击测试进度面板工具栏中可用的 Generate Report 按钮。
- 完成打开的报告对话框。
然后,将通知指定的审阅人员代码已准备好进行审阅。评审员可以按照 审阅者 - 审查代码修改中所描述执行评审。
评审完成后,作者可以按照 作者 - 审查和回应审查意见中所描述做出响应。
向代码评审包添加新文件
若要将选定的文件添加到现有的代码评审包中:
- 在项目树中,右键单击要向其添加文件的包,然后从快捷菜单选择 Parasoft> Add to> Code Review 。
- 完成“代码评审助手”对话框。
使用属性文件定义审阅者、作者和监视器
除了在测试配置中直接指定代码评审用户,并在代码评审助手对话框中“实时”添加评审人员之外,你还可以在 .properties 文件中定义代码评审用户。如果你的评审过程涉及大量的团队成员,并且你可以自动生成团队成员的数据库,那么这将非常有用。
若要使用属性文件定义审阅器:
- 请准备空的属性文件
config.properties
。 将以下初始所需数据添加到其中:
com.parasoft.xtest.checkers.api.config.name=Base Code Review com.parasoft.xtest.checkers.api.config.tool=3 com.parasoft.xtest.codereview.scanner.checksum=fixed
开始定义用户列表(要么手动定义,要么使用自定义脚本自动提取适当的信息)。每个用户必须有一个索引,然后是属性,如名称、角色和监视的位置(仅适用于监视器)。可用的角色有 'a' (作者), 'm' (监视器), 'r' (审阅者)。例如:
com.parasoft.xtest.codereview.scanner.crusers.0.name=tom com.parasoft.xtest.codereview.scanner.crusers.0.roles=r com.parasoft.xtest.codereview.scanner.crusers.1.name=bob com.parasoft.xtest.codereview.scanner.crusers.1.roles=r com.parasoft.xtest.codereview.scanner.crusers.2.monitored.locations=**/src/**, **/include/** com.parasoft.xtest.codereview.scanner.crusers.2.name=joe com.parasoft.xtest.codereview.scanner.crusers.2.roles=am com.parasoft.xtest.codereview.scanner.crusers.3.name=bill com.parasoft.xtest.codereview.scanner.crusers.3.roles=a
- 在专用 HTTP 服务器上发布准备好的文件。如果要基于用户数据库自动重新生成此文件,请使用允许此类重新生成的文件位置。
- 打开测试配置对话框,通过复制“预提交”测试配置创建新的配置。
- 右键单击该测试配置,选择 New Child,然后将 URL 地址键入 HTTP 父配置。
- 刷新测试配置管理器,并验证是否显示了任何添加的监视器。
- 在团队服务器上发布它。
下面是一个示例属性文件:
com.parasoft.xtest.codereview.scanner.crusers.13.roles=arm com.parasoft.xtest.codereview.scanner.crusers.13.name=dave com.parasoft.xtest.codereview.scanner.crusers.13.reviewers=mark_A, mark_B com.parasoft.xtest.codereview.scanner.crusers.13.monitors=mike com.parasoft.xtest.codereview.scanner.crusers.13.reviewed.locations=**/test/*.txt, project_A/** com.parasoft.xtest.codereview.scanner.crusers.13.monitored.locations=/** com.parasoft.xtest.codereview.scanner.checksum=fixed
注意:
- 数字 13 是配置中此用户的唯一 id。
- 角色“arm”代表 author/reviewer/monitor。特定字母的出现表明该用户具有相应的角色。例如,角色“rm”意味着他应该包括在建议的 reviewers/monitors 列表中,但是他不是作者(不会为他的修订创建任何审阅)。
- reviewers/monitors 是一个用户列表,应该自动分配给这个用户所编写的包(需要角色 author=true)。
- 所审阅/所监视位置是一个区域列表,该用户应该被分配为审阅者/监视者(要求角色 reviewer/monitor=true)。
- 如果其他用户在他的 reviewers/monitors 列表中指定了“dave”,则还需要 'dave’的 reviewer/monitor=true。
- 只需要唯一的 id 和用户名,但是每个用户必须至少激活一个 author/reviewer/monitor 角色才能有意义
- 为避免应用程序的旧版本覆盖此配置,需要 checksum=fixed 这样一个键。
将提交后扫描添加到提交前流程
有些通过预提交过程提交代码供评审的团队也喜欢执行提交后的夜间扫描,以便:
- 生成邮箱,通知作者和审阅者他们所分配的代码评审任务。
- 识别提交给源代码控制但未使用预提交过程提交审查的任何代码变更。
有关如何实现此功能的详细信息,请查阅 Running Post-Commit Scans with a Pre-Commit。