CR模板使用指南
欢迎使用我们的代码托管平台!为了提高代码评审(Code Review, CR)的效率和质量,我们为您提供了一系列 Code Review 模板功能。这些模板旨在帮助您标准化审核流程、减少人为错误,并确保代码的质量。下面将详细介绍如何使用这些模板,以及如何创建和应用自定义模板以适应您的开发流程。 我们平台支持以下两种类型的 CR 模板:
代码评审详情模板:用于描述代码变更的详细信息,帮助评审者了解变更的上下文、目的和效果。
代码评审合并模板:用于标准化合并请求的信息,确保合并过程的清晰和规范。
代码评审详情模板
内置模板
我们提供了五种内置的代码评审详情模板,分别适用于不同的评审情景:
标准模板
适用于一般的代码变更审查。该模板的示例如下:
## 评审的动机和背景
<!--
详细描述您的代码评审的作用及其原因。
请随时更新此描述以进行任何讨论,以便 以便评审者能够理解你的意图。
保持描述的更新对于没有参与讨论的评审者来说尤为重要。
-->
## 效果展示(支持屏幕截图或者录屏)
_如果存在UI上的改动,推荐上传截图或者录屏_
| 之前 | 之后 |
| ------ | ------ |
| | |
## 如何进行配置和测试验证?
<!---
详细描述运行测试环境、配置、测试过程、结果等信息。
-->
## 验收清单(Checklist)
该清单鼓励我们确认所有变更均已进行分析,以降低质量、性能、可靠性、安全性和可维护性方面的风险。
<!--
* [ ] 我已经评估了该代码仓库需要遵循的评审规范
-->
## 关联的工作项以及资料等
<!--- 关联的任务链接 -->
<!--- 相关文档链接 -->
详细模板
包含更多的细节,用于需要更深入审查的复杂代码变更。该模板的示例如下:
## 评审的动机和背景
<!--
详细描述您的代码评审的作用及其原因。
请随时更新此描述以进行任何讨论,以便 以便评审者能够理解你的意图。
保持描述的更新对于没有参与讨论的评审者来说尤为重要。
-->
## 评审类型
<!-- 可按需删除不相关的选项或新增类型:-->
* [ ] 缺陷修复(非破坏性改动的方式进行缺陷修复)
* [ ] 特性开发(非破坏性改动的方式进行特性功能开发)
* [ ] 破坏性改动(可能会导致现有功能产生非预期的结果)
## 评审的测试情况
<!--
请描述为了验证此更改而运行的测试情况,必要时请提供对应的说明。
例如测试的配置和参数等详细信息,以便可以进行重现。
-->
* [ ] UT(单元测试)
* [ ] SIT(集成测试)
* [ ] PT(性能测试)
<!--
测试配置情况,可按需删除不相关的选项或新增类型。
-->
* 测试版本:
* 测试环境:
* 测试工具链:
* 测试SDK版本:
# 验收清单(Checklist)
该清单鼓励我们确认所有变更均已进行分析,以降低质量、性能、可靠性、安全性和可维护性方面的风险。
<!--
例如:
* [ ] 我已经评估了该代码仓库需要遵循的评审规范
下列选项,可按需删除或新增:
-->
* [ ] 我的代码遵循该项目的代码风格
* [ ] 我已经对我的代码进行了自我审查
* [ ] 我对我的代码进行了注释,特别是在难以理解的区域
* [ ] 我对文档做了相应的修改
* [ ] 我添加了单元测试来证明改动有效
* [ ] 新的和现有的单元测试在我本地可以运行通过
缺陷描述模板
专门为bug修复和问题追踪的评审设计。该模板的示例如下:
## 缺陷描述
<!--- 缺陷的影响面和严重程度 -->
* [ ] Critical(严重缺陷:可能导致系统崩溃或损坏,需要立即修复)
* [ ] Major(一般缺陷:影响产品功能,需要进行排期修复)
* [ ] Minor(轻微缺陷:对功能影响较小,但是仍然存在隐患,需要进行排期修复)
## 预期结果
<!--- 预期的行为是什么? -->
## 实际结果
<!--- 实际发生了什么? -->
## 重现步骤
<!--- 如何重现该问题? -->
## 修复前后效果(支持屏幕截图或者录屏)
_如果存在UI上的改动,推荐上传截图或者录屏_
| 修复前 | 修复后 |
| ------ | ------ |
| | |
## 报错日志
<!--- 推荐使用代码块 (```) 格式化控制台输出内容、日志或缺陷代码-->
## 问题定位
<!--- 问题代码行链接等信息 -->
## 修复方案
<!--- 你是如何修复该问题的? -->
功能开发模板
适用于新功能开发的代码评审。该模板的示例如下:
## 需求概括
<!--- 简洁总结该需求功能 -->
## 需求来源和功能描述
<!--- 该需求和功能主要解决什么问题? -->
## 需求功能的实现方案是什么?
<!--- 如何实现该需求功能? -->
## 新功能的测试用例是否补齐?
<!--- 涉及了哪些测试用例,在评审中是否涵盖? -->
优化改进模板
针对性能优化和代码改进的评审。该模板的示例如下:
## 优化目标
<!--- 简洁总结优化目标和效果 -->
## 优化类型
<!--- 选择本次优化的类型 -->
* [ ] 代码重构
* [ ] 体验优化
* [ ] 性能优化
## 优化改进描述
<!--- 本次优化解决什么问题? 目标和效果是什么? -->
## 优化改进方案
<!--- 如何实现本次优化? -->
## 优化改进效果
<!--- 优化改进效果对比 -->
自定义模板
如果内置模板不能满足您的需求,您可以创建自定义的代码评审详情模板。自定义模板的识别基于以下规则:
条件1:在默认分支的仓库根路径下的
.aliyun
、.github
或.gitee
目录创建名为pull_request_template.md
的文件。条件2:在默认分支的仓库根路径下的
.aliyun/PULL_REQUEST_TEMPLATE
、.github/PULL_REQUEST_TEMPLATE
或.gitee/PULL_REQUEST_TEMPLATE
目录创建任何.md
后缀的文件。条件3:在默认分支的仓库根路径下的
.gitlab/merge_request_templates
目录创建名为default.md
的文件。
这些文件路径和模板名称不区分大小写。
如何使用代码评审详情模板
创建合并请求
在创建合并请求页面,点击“新建合并请求”按钮。
在描述区域下方,系统将展示可用的代码评审详情模板,包括内置模板和您的自定义模板。您也可以从描述区域的右上方的下拉菜单“描述模板”选择您想要使用的代码评审详情模板。
选择相应的模板后,模板内容将自动填充到合并请求的详细信息中,您可以根据需要进一步进行编辑。
浏览,编辑,创建模板文件
为了简化您的工作流程,我们的平台提供了智能模板识别功能,在您与模板文件交互时自动提供帮助和指引。 当您在浏览文件时,如果系统检测到文件是一个模板文件,它将在浏览器界面上显示一个明显的提示。这样,您可以轻松地辨识出当前文件是否为模板,并按照模板格式进行相关操作。
当您在编辑文件时,如果系统检测到文件是一个模板文件,它将在浏览器界面上显示一个明显的提示,确保您在修改时可以遵循模板的规范。
当您在创建新文件时,如果您的文件命名和结构符合模板文件的规则,系统也将提示您该文件是模板文件。这有助于您在创建时即刻了解文件的模板性质,从而正确使用模板。此外,为了进一步提高您的效率,我们允许您在创建自定义模板时直接使用云效提供的5种内置代码评审详情模板。您可以选择一个内置模板作为起点,然后根据您的具体需求进行自定义和扩展。
创建代码库时选择合并请求模板
在创建新的代码库时,您现在可以轻松启用默认的合并请求模板。操作方法如下:
在创建代码库过程中,勾选“创建合并请求模板”选项。
从下拉菜单中选择一种云效提供的内置代码评审详情模板。
系统会自动在默认分支的
.aliyun
文件夹下创建一个名为pull_request_template.md
的模板文件。
依靠这些功能,您可以保证您的工作流程更加高效,并且与您的团队成员在提交和审查代码时保持一致性。
代码评审合并模板
内置模板
我们提供了两种内置的合并模板,用于标准化合并请求信息:
默认普通合并模板
用于普通的代码合并操作。该模板的示例如下:
Merge {{cr_id}} into {{cr_target}} from {{cr_source}}
{{cr_title}}
* {{cr_source}}: ({{cr_commits_count}} commits)
{{cr_commits_oneline}}
{{cr_author}}
{{cr_commentators}}
{{cr_reviewers}}
{{cr_submitter}}
{{cr_link}}
默认压缩合并模板
用于在合并时压缩多个提交。该模板的示例如下:
Merge {{cr_id}} into {{cr_target}} from {{cr_source}}
{{cr_title}}
* {{cr_source}}: ({{cr_commits_count}} commits)
{{cr_commits_full}}
{{cr_author}}
{{cr_commentators}}
{{cr_reviewers}}
{{cr_submitter}}
{{cr_link}}
自定义模板
如果内置模板不能满足您的需求,您可以创建自定义的代码评审合并模板。自定义模板的识别基于以下规则:
普通合并模板:在
.aliyun/PULL_REQUEST_TEMPLATE/MERGE_TEMPLATE
目录下创建名为normal_merge_message.txt
的文件表示普通合并模板。压缩合并模板:在
.aliyun/PULL_REQUEST_TEMPLATE/MERGE_TEMPLATE
目录下创建名为squash_merge_message.txt
的文件表示压缩合并模板。
文件路径和模板名称不区分大小写。
模板渲染
我们的代码评审合并模板利用Mustache
模板引擎进行变量渲染,以便快速且灵活地生成合并信息。接下来,我们将介绍支持的模板变量以及Mustache语法的基本规则。
支持的模板变量
在您的代码评审合并模板中,您可以使用以下变量来自动填充信息:
字段名 | 说明 | 示例 |
| 评审ID |
|
| 来源分支 |
|
| 目标分支 |
|
| cr标题 |
|
| cr描述 |
|
| 作者 |
|
| 评审者(所有评审人,包括通过、未通过、未表态) |
|
| 评审通过人 |
|
| 合并人 |
|
| 评论人 |
|
| 评审链接 |
|
| 评审提交数 |
|
| 提交信息(简略版) |
|
| 提交信息(详细版) | 包含提交标题与提交描述的完整提交信息格式 |
Mustache模板引擎语法简介
Mustache是一个逻辑简单的模板系统,通常称为“无逻辑”模板。它可以使用于HTML、配置文件、源代码等。模板标签使用双花括号({{ 和 }})包围。以下是Mustache基本语法:
变量渲染
变量是Mustache模板中的基本插值类型。当模板中的标签与视图中的属性匹配时,它将被替换为对应的值。
Hello, {{name}}!
如果视图对象是 { “name”: “John” },那么输出将是:
Hello, John!
列表渲染
假设你的变量是一个列表,比如你有一个代表人员列表的数组。
{
"people": [{"name": "Alice"},
{"name": "Bob"},
{"name": "Charlie"}]
}
你的Mustache模板可以设计为:
People:
{{#people}}
- {{name}}
{{/people}}
在这个例子中,{{#people}}
开始了一个Section
,该Section对应视图对象的 people 数组。Mustache将为列表中的每个条目渲染 - {{name}}
。当所有条目都被渲染后,{{/people}}
表示Section的结束。渲染后的文本将是:
People:
- Alice
- Bob
- Charlie
转义与注释
Mustache默认会转义HTML字符,避免XSS攻击。如果你不想输出的变量被转义,可以使用三花括号:
Hello, {{{name}}}!
如果name的值是 “John”,那么输出将是:
Hello, <b>John</b>!
而不是转义后的:Hello, <b>John</b>!。
Mustache中的注释使用 {{! comment}}
。这些注释不会出现在最终的输出中。
如何使用代码评审合并模板
当您准备合并一个合并请求时,您可以选择合并方式。根据您的选择(普通合并或压缩合并),系统将使用相应的合并模板来填充合并信息。
将合并请求进行合并
在合并请求详情页面,找到并点击“合并”按钮。
方式1:选择“创建一个合并节点”。当选择这种方式进行合并时,所有的提交会以独立节点的形式加入到目标分支中。系统将会根据自定义代码评审合并模板规则检查您的仓库,以确定是否有自定义的普通合并模板:
如果发现自定义普通合并模板,系统将使用该模板来渲染合并信息。
如果没有自定义普通合并模板,系统将使用内置的普通合并模板。
如下图所示:
方式2:选择“Squash合并”。所有的提交会被压缩成一个单一的提交再合并到目标分支。系统将会根据自定义代码评审合并模板规则检查您的仓库,以确定是否有自定义的压缩合并模板:
如果发现自定义压缩合并模板,系统将使用该模板来渲染合并信息。
如果没有自定义压缩合并模板,系统将使用内置的压缩合并模板。
如下图所示:
浏览,编辑,创建模板文件
当您在浏览文件时,如果系统检测到文件是一个模板文件,它将在浏览器界面上显示一个明显的提示。这样,您可以轻松地辨识出当前文件是否为模板,并按照模板格式进行相关操作。
当您在编辑文件时,如果系统检测到文件是一个模板文件,它将在浏览器界面上显示一个明显的提示,确保您在修改时可以遵循模板的规范。
当您在创建新文件时,如果您的文件命名和结构符合模板文件的规则,系统也将提示您该文件是模板文件。这有助于您在创建时实时了解文件的模板性质,从而正确使用模板。
此外,为了进一步提高您的效率,我们允许您在创建自定义模板时直接使用云效提供的2种内置代码评审合并模板。您可以选择一个内置模板作为起点,然后根据您的具体需求进行自定义和扩展。