新版合并请求

1. 创建代码评审

1.1. 基础信息

创建代码评审由以下几个步骤组成：

• 选择来源和目标分支。用户可以根据自身需要，选择来源于目标分支，如果不存在diff或者diff过大，我们会为你进行详细的提示和下一步的操作引导。

• 分支选择完成后，我们会将分支指向的最新提交（tip commit）、提交时间、提交SHA等信息为你进行展示。

• 我们会为用户展示三个模块，分别为“基础信息”、“提交列表”和“文件改动”，用于指引下一步合并请求的创建，下面针对这三个模块，我们将分别介绍。

基础信息模板分为以下几个部分，用户可以根据需要进行编辑：

• 评审标题：默认会摘选提交信息中的标题进行自动生成。

• 标记为开发中（WIP）：用户可以选择是否在创建合并请求的同时，将合并请求的状态设置为“开发中”（Work In Progress）。开发中状态的评审不会向评审参与者发送消息通知，方便评审作者前期进行频繁更新，待准备就绪后通过去掉标题的“[wip]”前缀或者在评审详情页中执行“取消wip状态”操作，来推进评审进入“评审中状态”。

• 评审描述：用户可以填写评审的描述信息，目前Codeup提供了6种内置模板进行选择，分别为：

  • 标准模板

  • 详细模板

  • 缺陷描述模板

  • 功能开发模板

  • 优化改进模板

  • 提交说明模板

  除此之外，我们还支持用户自定义合并请求模板功能，用户可以根据自己的需要进行定制，参见CR模板使用指南。

• 评审人编辑：支持在创建合并请求时，完成评审人的添加。我们同时提供了推荐的代码评审人信息，方便用户直接添加。

• 类标（Labels）：支持在创建新版合并请求时，完成类标的添加。

• 关联工作项：支持关联云效Projex中的需求、缺陷、任务等工作项类型。

1.2. 提交列表

当切换到“提交列表”时，可以由近及远地查看各个提交信息，复制提交SHA以及进行提交详情页跳转。

1.3. 文件改动

当切换到“文件改动”时，可以查看具体的文件改动差异。当一些准备就绪后，点击“确定”按钮便可以完成评审的创建。

2. 基于补丁（Patch）的评审工作流

2.1. 代码评审详情页首屏视图介绍

Codeup新版代码评审详情页的首屏视图，主要分为5个区块，下面将分别介绍各个区块。

2.1.1. 基础信息区-A

基础信息区-A的作用是，用户可以快速定位评审核心信息，以及评审流程操作入口。将其放置在评审视图的最顶端，符合用户评审工作流的关注顺序。方便用户查看具体信息以及执行高频操作：

• 查看和修改合并请求标题。

• 查看合并请求状态。

• 查看作者信息。

• 查看源分支（提交）和目标分支，支持对目标分支进行切换。

• 查看源分支相比目标分支的领先和落后的提交数。

• 点击“通过”或者“不通过”，进行评审表态。

• 点击“...”，包含的更多操作如下：

  • 关闭合并请求。

  • 下载合并请求。

  • 设置WIP标记（取消WIP标记）。

2.1.2. 基础信息区-B

基础信息区-B的作用是，让用户了解评审工作流的阻塞项和解决方案。基础信息区-B放在比较突出的位置，包含了当前评审继续推进到最终合并，还存在哪些问题，例如代码冲突问题，用户自定义的卡点门禁等。基础信息区-B的展示内容称之为“合并卡点信息”，各个评审的参与角色，都可以一眼洞悉当前评审的进程，并且知晓下一步action。

2.1.3. 基础信息区-C

基础信息区—C的作用是，了解与当前评审的关联信息。关联的信息本质上不属于代码层面的元数据，而是为了辅助工作流运转的相关数据。例如，评审人展示和修改、类标的添加和删除、工作项的展示和关联（解除关联），这些信息通常不会非常频繁修改，所以放置在右侧的次要位置。

2.1.4. 基础信息区-D

基础信息区—D的作用是，让处于评审工作流的参与者，从不同的维度更细致地了解代码评审。因为首屏的信息的布局有限，对于不同维度的详细评审信息的展示问题，我们扩展了4个对应模块来解决，分别为：

• 概览：查看和编辑评审信息、查看和筛选评审动态、发表全局评论。

• 文件改动：查看具体改动的文件列表，文件内容diff。

• 提交改动：从提交的维度，查看评审的改动，包括列表和区间两个评审维度。

• 自动化检查：从CI/CD等维度，查看已集成的自动化检查的运行结果。

2.2. 评审状态流转

在代码评审的过程中，一般需要多轮次的评审改动，产品背后的逻辑是需要支持评审循环迭代过程中的状态轮转。简单清晰的评审状态机，在这里至关重要。新版合并请求中，我们简化了评审状态设计，总共抽象为4种状态，以下为各个状态的说明以及状态流转示意：

2.3. 更新代码评审

2.4. 评审更新的快照——补丁（Patch）

补丁（Patch）是Codeup新版合并请求的更新单位，每当用户对评审进行更新（例如，执行了一次git push）之后，Codeup会自动计算推送的最新提交与当前评审版本的比对，从而新生成一个评审版本，从而完成评审的更新。

不论评审的周期长短，每次只要用户对原分支的提交版本进行更新，Codeup都会自动为用户在保存已有版本的 Snapshot的同时，为用户生成新的 Snapshot，在 Git 的术语中，称为一个补丁（Patch）。在代码评审的流程中，在 SnapShot 中只记录 Git 相关的提交信息是远远不够的。因为评审往往存在多轮，即“循环迭代”的过程，通过一次代码评审的核心流程图，可以比较清楚地了解：

对于某一次Patch的评审，新版合并请求不仅仅会留下代码补丁对应的提交信息，还会衍生出其他一系列信息：

• 文件改动（代码Diff）。

• 评论。

• 自动化检查（CI）结果。

• 评审表态信息，如通过、不通过。

• 修改标题、描述、增删评审人等基础信息变更。

• ...

Codeup 会自动保存每个 Patch 衍生的全部信息，并且支持Patch与Patch之间的多维度信息对比，帮助解决评审颗粒度过粗，以及评审者难以从评审上下文中恢复，甚至经常需要重新进行 Review 的问题。在下面的文档章节中，我们对每一个产品模块，为大家进一步详细阐述基于Patch的评审工作流在其中发挥的关键作用。

3. 文件改动模块

刚才我们介绍了基于Patch的评审工作流，下面我们看下如何使用文件改动模块的相关产品功能。

3.1. 查看代码改动差异

当点击横向导航栏中的“文件改动”选项，我们将为您展示文件改动差异视图，主要分为三部分区块：

• 【红色框】补丁版本区间选择（Patch）：我们可以通过该组件灵活的完成Patch版本的区间切换。默认的，我们将为用户展示评审的合并基线（左侧“Base”，即来源分支与目标分支的Merge Base），以及当前最新补丁版本（当前评审最新Patch为“版本1”）之间的差异。

• 【蓝色框】文件树：可以通过该组件快速的完成评审文件树的浏览和切换。同时我们在文件上标识了三类信息，分别是：

  • 文件修改类型。

  • 已读和未读的信息标注（蓝色圆点）。

  • 新增和删除的行数。

• 【绿色框】差异视图：展示对应文件的改动差异。

3.2. 文件改动的视图设置

不同的用户对于文件改动存在不同的评审习惯，针对类似的用户诉求，我们沿用并新增了部分视图方面的设置，并将自动记忆用户的配置习惯，其中包括：

• Diff视图配置，切换单栏或双栏展示。

• 文件浏览模式配置，平铺模式或逐个浏览模式。

• 是否展示改动空格配置。

• 是否展示评论配置。

• 是否支持换行展示配置。

3.3. 已读与未读

除了在文件树上展示关于文件的已读与未读信息之外，我们支持用户手动标注已读与未读信息，从而方便的记录自己希望额外关注或者多次阅读的文件。二者都是在基于Patch的评审工作流的基础上完成，即针对不同版本下文件的已读和未读的信息，codeup都将全部进行自动的持久化，不论用户如何切换版本，Codeup都将为用户展示特定补丁版本之下文件已读状态的准确信息，提升评审效率。

3.4. 切换不同Patch之间的文件改动

针对一个已经创建的评审，若此时我们向分支执行了一次推送（例如，截图中修改了git-notes.txt文件并推送到评审的源分支）。新版合并请求会根据已经推送上来的提交，自动生成新的补丁，将代码评审自动更新为“版本2”。对于评审的参与者，可以在【红色框】的补丁版本组件上切换我们想要review的版本，如：Patch-1已经评审过了，当前只需要看Patch-1 和 Patch-2之间的差异即可，效果如下：

4. 提交改动模块

在文件改动量级较小时，评审者通过文件改动通常可以满足高效评审的诉求。但当文件改动的规模较大时，评审的复杂度和难度会随之增加，我们希望用户使用“提交改动”选项来解决一定程度的这类问题。

在新版合并请求中，当我们点击横向导航栏中的“提交改动”选项，将进入到提交改动模块。提交改动视图主要用于帮助从提交维度入手进行评审，提升评审效率。在提交改动模块中，我们提供了两种不同的评审视图，用户可以进行手动切换，用来解决不同场景的问题：

• 提交列表： 类似 git log 命令，由近及远的展示特定 Patch 提交列表。

• 版本差异： 类似 git range-diff, 查看两个 Patch 之间的提交改动信息。

在“提交改动”模块内，仍然可以看到基于Patch评审工作流的影子，不管在提交列表或者版本差异的视图中，都支持切换评审中的Patch版本。提交列表更适用于首次评审场景，对所有提交进行全量评审。而版本差异适合多次补丁迭代评审的场景，可以帮助评审者有效控制评审范围，使其更加关注版本的变化，进行增量评审。

关于提交列表和版本差异的不同使用场景，我们已经在文档通过 “提交列表” 快速了解最新改动，进行全量评审中进行详细介绍，推荐大家进行阅读。

5. 自动化检查模块

Codeup提供了开箱即用的流水线和代码检测能力，让用户可以快速、低成本的完成CI服务的集成。当用户点击横向导航栏上的自动化检查选项时，便可以查看已集成在合并请求中自动化检查的运行结果，并支持通过切换代码评审Patch版本，追溯历史自动化检查结果。自动化检查的集成方式有三种，下面我们将依次进行具体介绍：

• 云效Codeup代码检测集成

• 云效Flow流水线集成

• 三方自动化检查集成

5.1. 云效 Codeup 代码检测集成

Codeup内置诸多代码检测能力，支持与代码评审进行轻松集成，可参考文章代码检测。Codeup代码检测集成后，支持如下几个能力：

1. 支持代码检测状态实时回写。

2. 支持代码检测运行详情的前端嵌入，提升使用体验。

3. 支持快捷跳转到Codeup代码检测任务详情页。

5.2. 云效 Flow Pipeline 集成

Codeup代码评审支持与云效Flow进行轻松集成，具体可参考文章如何关联 Flow 流水线。云效Flow流水线完成集成后，代码评审支持如下几个能力：

1. 代码评审展示的流水线的状态为实时回写，并会在页面自动完成更新。

2. 支持云效流水线运行详情的前端嵌入，提升使用体验。

3. 支持快捷跳转到云效流水线详情页。

5.3. 三方自动化检查服务集成

5.3.1 基于提交状态（Commit Status）能力进行三方CI集成

5.3.1.1 基于OpenAPI完成数据回写

支持用户基于Codeup的提交状态（Commit Status）能力进行三方CI集成，当用户通过提交状态的OpenAPI回写CI结果数据之后，提交状态将自动集成进入代码评审的“自动化检查”中，作为代码评审的三方自动化检查结果进行展示，称之为“三方提交状态”，具体可参考API文档CreateCommitStatus - 添加提交状态记录，支持：

1. 状态回写：支持回写success、failure、pending、error四个状态。

2. 链接回写：支持回写链接，用于跳转到三方查看执行详情。

3. 描述回写：支持回写描述信息，并支持Markdown格式进行渲染。

5.3.1.2 基于提交状态（Commit status）设置合并卡点

在日常开发中，可以通过设置提交状态的卡点，以阻止不满足卡点要求的合并请求进行合并。该配置在「库设置」->「分支设置」->「保护分支规则」设置中，如下图所示：

5.3.2 基于检查运行（Check Runs） 能力进行三方CI集成

除了提交状态（Commit Status）进行三方CI集成的方式之外，Codeup还提供了另外一种三方CI集成的方式：检查运行（Check Runs）。提交状态本身简单容易接入，但对于职能细分、强评审工作流的团队而言难免捉襟见肘，这时候就需要一种扩展能力强、定制化程度高的三方集成能力。

检查运行（Check Runs）特性，即为这种情况而设计，其不仅提供了更为丰富的CI状态枚举，检查注释（Check Annotations）信息以及在Codeup的代码评审中自定义结果展示视图（基于回写的Markdown格式渲染）。

整个检查运行的生命周期都基于OpenAPI来完成流程设计和实现。详细的API信息，请参考API文档：检查运行。

5.3.2.1 Check Runs支持丰富的CI状态

检查运行（Check Runs）的状态通过两个参数字段 status 和 conclusion决定，用户在使用时，可以根据实际自动化检查结果进行状态映射。

• status 包含：

  • queued：排队中

  • in_progress：运行中

  • completed：已完成

• conclusion 包含（当status为completed时，conclusion才会写入生效）：

  • cancelled：已取消

  • failure：失败

  • neutral：中立状态（通常该状态用于「需要执行自动化检查，但不影响最终结果或可以忽略」，计为成功状态）

  • success：成功

  • skipped：跳过（计为成功状态）

  • timed_out：超时（三方检查的超时时间）

  • stale：过时（由代码平台决定，超过14天且状态仍然未达到status=completed时，会被平台处理为stale，并且只有代码平台才能将check runs的conclusion设置为stale，用户无法通过回写设置该状态）

5.3.2.2 检查输出（Check Ouput）能力介绍

用户通过OpenAPI回写output字段，可以定制化某一个检查运行（Check Runs）的详情展示。如果你存在类似的个性化诉求，此部分是UI展示的重点信息字段：

• output包含：

  • title：标题信息（非check runs的name）

  • summary：摘要信息，支持 Markdown格式，最大字符长度为64KB，即65535个字符

  • text：详情信息，支持Markdown格式，最大字符长度为64KB，即65535个字符

  • images：该字段为需要展示的图片信息，通常不超过3张图片，并且需要确保能够被访问，否则可能无法展示

以下为output回写时，检查运行对应的展示：

5.3.2.3 检查注释（Check Annotation）能力介绍

检查注释提供了在代码检查中直接针对代码行、或者连续的代码片段进行注释信息添加的能力。在实践中，当CI可以返回具体代码行位置的问题时，通常也希望在评审界面也能直观地了解。检查注释通过OpenAPI进行回写，下面是具体的字段介绍：

• annotations包含：

  • path：文件路径

  • startLine：开始行，从1开始，这需要用户确保该行能够在path指定的文件中找到

  • endLine：结束行（同上）

  • startColumn：起始列（当且仅当startLine=endLine时，该字段有效）

  • endColumn：结束列（当前仅当startLine=endLine时，该字段有效）

  • annotationLevel：检查注释问题等级

    • notice：轻微

    • warning：警告

    • failure：严重

  • message：检查注释的摘要信息

  • title：检查注释的标题（这不是必需的，但实践上，我们建议标题用于指明代码行和问题，便于快速了解问题）

  • rawDetails：CI运行输出的原始内容（为普通文本格式不会进行特殊的渲染，限制64KB）

检查运行详情页展示：

代码评审差异（Diff）视图的展示：

5.3.2.4 基于检查运行（Check Runs）设置合并卡点

「代码库左侧导航栏」-> 底部「设置」-> 「分支设置」-> 「保护分支规则」-> 「新建或者编辑」

如果刚完成合并卡点的配置，此时还未有相应的检查运行数据回写，我们将会做如下展示（对应代码评审卡点项，Codeup基本保持了相同的逻辑，即卡点项一旦配置一定会在「自动化检查中」展示，即使它没有当前版本的检查记录）：

当回写数据后的产品展示：

没错，如果在保护分支中配置了自动化检查卡点，那么在合并请求的「自动化检查」导航栏下，相应的自动化检查项会被标记为卡点。除此之外，只有卡点项才会影响合并请求的合并准许，非卡点项仅展示，但不会阻塞，不过，我们并不建议您对「失败的非卡点项」忽略。

6. 评论能力介绍

新版代码评审，提供了诸多的评论能力，评论能够帮助参与评审的各个角色进行更好的反馈和响应，它不仅有助于提高当前的代码质量，还有助于团队的持续学习和进步。

6.1. 评论的状态与展示

当评论发出后，可以复制评论链接，方便分享。也支持针对评论内容再次编辑，或者删除。对于一个已发送的评论来说，大体可以分为两种状态：

1. 待解决：默认会进行视图展示，目的是帮助用户直观和快速定位待解决评论，用户可以点击“标记为已解决”按钮更新评论状态为“已解决”。

2. 已解决：默认我们会置灰并进行收起，目的是帮助用户屏蔽干扰（已解决通常意味着后续无需再关注），用户可以点击“标记为待解决”按钮更新状态为“待解决”。

6.2. 行内评论（文件评论）

上面介绍的例子，其实是行内评论演示。行内评论主要用于提供具体文件改动位置的针对性的反馈，使得讨论具体而集中。

6.3. 全局评论（整体评论）

全局评论也可以叫做整体评论，通常指的是针对整个评审进行的评论。它们用于提供更高层次的反馈，涵盖整体上的问题或讨论，或者讨论更加广泛的、衍生的主题。全局评论的入口位于动态底部，整体评论和行内评论在动态中有明确的样式区分。

6.4. 上下文回复和提及

不管是行内评论还是全局评论，都支持基于评论上下文进行回复，同时也可以提及其他用户参与讨论。

6.5. 草稿评论

草稿评论是代码评审过程中一个非常实用的功能，草稿意味着评论并没有实际发出，而只是对自己可见。草稿评论可以帮助评审者更加有效和有组织地提供反馈，它是一个思考和预备步骤，确保提交的评论是经过深思熟虑的，更有助于代码质量的提升。

草稿评论为淡黄色，与非草稿评论进行了明确的样式区分，草稿评论同时也支持针对内容本身进行更新，或进行删除。当草稿评论准备完毕，可以点击右上角“提交草稿”进行批量提交，点击后会展示如下信息：

• 文件名、评论行号（支持点击跳转）。

• 基于的Patch版本。

• 草稿评论的缩略信息。

当确认无误后，点击“立即提交”，草稿评论即可发出，进而提供给其他评审者进行反馈。

6.6. 动态表情评论

动态表情可以帮助传达语气和情感，使评论更具人情味，减少因文字表述不当而引起的误解，增强沟通效果，减少接受反馈时的心里压力。新版代码评审，支持4种动态表情评论分别表示：

• LGTM（Looks good to me！）

• 赞同

• 已阅

• 存疑

6.7. 评论的快速筛选

有时我们希望能够针对特定的评论进行筛选，例如快速定位待解决的评论，或者特定评审者需要关注的评论。Codeup新版合并请求，支持基于评论者、评论状态以及是否被提及，进行快速筛选，提升评审效率。

6.8. 待解决评论的迅速定位

为了更进一步快速处理待解决评论等待办事项，我们在右上角的位置放置了一个常驻的“待解决小组件”，不论用户当前身处哪个模块之下，都可以基于此组件完成待办事项的快速定位。用户只需要点击“向下”的箭头，便可以逐一的处理评审待办事项。除此以外，点击组件本身，将会具体展示不同类型的待解决问题列表，并支持点击跳转到对应位置。

7. 卡点门禁能力介绍

7.1. 合并卡点配置

新版代码评审兼容了轻评审与重评审的流程差异，可以灵活的进行卡点门禁的配置，并基于配置实时生效，严格根据用户要求满足合并条件后，方可执行合并操作。与此同时，我们支持4种通用的卡点场景配置，用户可以在保护分支设置中灵活选择开启，它们分别是：

• 代码冲突卡点。

• 评审通过人数卡点。

• 自动化检查卡点。

• 评论未全部解决卡点。

7.2. 卡点信息的展示

当配置对应的卡点后，如果触发了合并卡点的对应提交，我们将在新版代码评审中进行着重的提示，针对上面4类合并卡点，我们将依次进行具体介绍。

7.3. 代码冲突卡点与在线冲突解决

当存在代码冲突时，鼠标hover到代码冲突卡点时，将会提示冲突解决的解决方案，我们提供了两种解决冲突的方式：

• 使用在线冲突解决功能

• 本地更新下载最新代码并解决

如果冲突内容较多，推荐在本地进行冲突解决。

7.4. 评审通过人数卡点

当将鼠标hover“评审通过人数不足”的卡点时，将展示评审通过情况。

7.5. 评论未全部解决卡点

当点击“评论未全部解决”卡点时，将自动为我们切换为“概览”视图，并自动筛选出动态中的待解决评论。

7.6. 自动化检查未通过卡点

当我们鼠标点击“检查卡点未通过”时，将自动为我们切换为“自动化检查”视图，为我们呈现自动化检查运行情况。

8. Revert（回撤）与 Cherry-Pick（拣选）

Codeup提供了强大的分支管理和协作功能。其中，合并请求是 Codeup 中用于代码评审、讨论以及合并代码的核心功能。在合并请求中，Revert 和 Cherry-pick是两个非常实用的操作。

8.1. Revert

Codeup 新版代码评审的Revert功能允许你对已经合并的代码进行回撤。当一个合并请求被合并到主分支后，可能会发现其中包含了错误或是不希望的更改。此时，你可以使用 Revert 操作来回撤这个操作。Codeup支持两种方式来 Revert 某个合并请求：

• 直接 Revert。

• 生成一个用于进行 Revert 的分支，使用这个生成的新分支来创建一个新的合并请求，通过这个合并请求来还原之前已经合并的代码。

8.2. Cherry-pick

新版代码评审中的Cherry-pick功能允许你对已经合并的代码进行 Cherry-pick，这在处理 bug 修复或者将某个特定的功能从一个分支搬运到另一个分支时尤其重要。Codeup支持两种方式来 Cherry-pick 某个合并请求：

• 直接 Cherry-pick。

• 生成一个用于进行 Cherry-pick 的分支，并且使用这个生成的新分支来创建一个新的合并请求，通过这个合并请求将原合并请求的代码 Cherry-pick 到指定的分支。

除此之外，Cherry-pick 还支持选择是否"压缩提交"，“压缩提交"可以将合并请求中所有提交合并成一个提交Cherry-pick 到指定的分支上，如果不勾选"压缩提交”，则会将合并请求的提交逐个 Cherry-pick 到指定的分支。

9. 代码评审下载与本地应用

在新版合并请求详情页面上，您可以获取代码变更内容。以下是快速获取代码变更内容的步骤：

1. 访问合并请求详情页面。

2. 单击“下载合并请求”按钮，此举会引导您进入查看界面。

3. 在版本选择下拉框中选择源分支特定版本。例如：若选择版本 1，则会获取目标分支与源分支版本 1 之间的变动内容。

具体请参考以下示意图：

我们共提供了 4 种获取合并请求改动内容的方案，下面我们将一次介绍。

9.1. 方案1——下载并检出到新分支：

执行下述命令，将从远程下载特定的合并请求引用refs/changes/<mr-id>/<patch-id>， 然后在本地仓库中创建一个新的分支<branch-name>并切换到这个新分支上去。

git fetch origin refs/changes/<mr-id>/<patch-id> && git checkout -b <branch> FETCH_HEAD

注意：当您想要在本地查看或继续工作在这个特定的变更上，并且希望这些变更在一个新的分支上进行时，您会使用这个命令组合。

9.2. 方案2——下载并检出到提交号：

执行下述命令将从远程仓库 origin 下载特定的代码变更引用refs/changes/<mr-id>/<patch-id>，然后在本地仓库中检出该修改，即把工作目录更新为该修改的内容。

git fetch origin refs/changes/<mr-id>/<patch-id> && git checkout FETCH_HEAD

注意：这个命令不会创建新的分支，当您想要临时审查或测试一个变更，且不打算在这个变更的基础上进行长期工作时，您可能会使用这个命令。

9.3. 方案3——下载并拉取到当前分支：

执行下述命令将从远程仓库 origin 下载特定的代码变更引用refs/changes/<mr-id>/<patch-id>，然后把拉取的变更合并到本地的当前分支中，这个命令实际上是 git fetch 和 git merge 的结合体。

git pull origin refs/changes/<mr-id>/<patch-id>

9.4. 方案4——下载文件

下载文件的两种不同格式：

• 单击 “补丁（Patches）文件” 下载链接即可下载对应的补丁文件。

• 单击 “差异（Diff）文件” 下载链接即可下载对应的差异文件。

注意：为确保下载流畅，Patch/Diff 总文件的大小上限为 24MB，超过大小则会下载失败。如果需要，我们强烈推荐您选择前面三种方案，或者在本地手动生成 Patch 或 Diff 文件， 可以执行下述命令：

git format-patch <from-commit>..<to-commit> --stdout >changes.patch

上述命令会在您的本地生成一个名为 changes.patch 的补丁文件，其中包含了<from-commit>和<to-commit>之间的变更。

git diff <from-commit> <to-commit> >changes.diff

上述命令会在您的本地生成一个名为 changes.diff 的差异文件，其中包含了<from-commit>和<to-commit>之间的差异。

9.4.1. Patch/Diff 文件的差异

9.4.1.1. Diff 文件

Diff 文件用来展示两个提交之间的差异，或是比较工作目录中当前文件和索引（或指定 commit）的差异。它通常用于本地查看修改或准备将变更加入暂存区的过程中。它是一个纯文本格式的差异描述，这个格式被称为 unified diff。该输出通常包括行前缀 + 表示添加的行，- 表示删除的行。如下展示的是一个具体的 Diff 文件：

9.4.1.2. Patch 文件

Patch 文件是一系列的补丁文件，每个补丁对应一个或多个 commit。这些补丁文件是可以通过电子邮件发送并应用到另一个仓库的。Patch 文件不仅包含代码差异信息，还包含了 commit 信息（如作者、日期和 commit 消息等），以及用于邮箱格式的额外头部信息。如下展示的是一个具体的 Patch 文件：

在 Git 的世界里，Diff 和 Patch 文件在本质上承载着相似的任务，即准确地记录代码的变更。当决定使用哪种文件时，您的目标决定了您的选择：如果您的目的仅仅是为了审视代码之间的不同，Diff 文件本身就能满足需求；但如果您需要将一连串的修改共享出去，或者想要将这些更改迁移到另一个代码库，Patch 文件便显得尤为合适。这种格式不仅包含了变更的详细内容，还携带了足够的信息来支持跨环境的版本控制协作。

9.4.2. 如何应用 Patch/Diff 文件到本地仓库进行评审？

9.4.2.1. 离线代码审查

使用 Diff 文件进行离线审查，以便在无需网络连接的情况下检视代码差异，并进行代码评审。

9.4.2.2. 使用 git apply 应用补丁

1. 切换至本地代码库目录：

 cd /path/to/your/repository

1. 使用以下命令应用 Patch 文件：

git apply /path/to/changes.patch

git apply 命令支持多个选项，例如：

• –stat：显示补丁文件的变更统计信息。

• –check：检查补丁文件是否可被应用，而不实际执行应用。

• –apply：实际应用补丁（通常为默认操作，一般无需指定）。

• –whitespace=option：检查空白字符错误。

• –reverse：反向应用补丁。

9.4.2.3. 使用 git am 应用补丁

1. 切换至本地代码库目录：

 cd /path/to/your/repository

1. 使用以下命令应用 Patch 文件：

git am /path/to/changes.patch

git am 命令还有一些实用的选项，例如：

• –signoff(-s)：在提交的末尾添加一个“Signed-off-by”行，表明您有权提交此补丁，并同意相关协议。

• –3way(-3)：如果补丁不能直接应用，则尝试三方合并。

• –skip：跳过当前补丁。

• –resolved：在解决冲突后，告诉 Git 继续应用下一个补丁。

如果在应用补丁的过程中发生冲突，git am 将停止应用补丁，并允许您手动解决冲突。解决冲突后，可以使用如下命令来继续应用补丁：

git am --resolved

或：

git am --continue

要放弃补丁的应用并恢复到原始状态，可执行：

git am --abort

12. 代码评审模板管理与定制

Codeup新版代码评审支持灵活定制的描述信息模板以及合并提交模板，具体参考文档：CR模板使用指南。

13. 推送评审模式

Codeup支持在不需要安装任何工具的情况下，执行原生的git push命令就可以自动创建和更新代码评审，并且能够支持对提交进行评审，而无需在远端创建分支。具体请参考文档：推送评审模式

$ git push
枚举对象中: 4, 完成.
对象计数中: 100% (4/4), 完成.
使用 12 个线程进行压缩
压缩对象中: 100% (2/2), 完成.
写入对象中: 100% (3/3), 340 字节 | 340.00 KiB/s, 完成.
总共 3（差异 0），复用 0（差异 0），包复用 0
remote: +-----------------------------------------------------------------------------------+
remote: | The following tips are provided by Codeup: |
remote: +-----------------------------------------------------------------------------------+
remote: | Merge request #31620 has been updated, please visit: |
remote: | https://codeup.aliyun.com/61234c2d1bd96aa110f27b9c/demo/merge_request/31620 |
remote: +-----------------------------------------------------------------------------------+
To https://codeup.aliyun.com/61234c2d1bd96aa110f27b9c/demo.git
 27e76f582c..e00db4522f master -> refs/merge-requests/31620/head

14. 分支标签评审模式

推送评审使用评审的形式来对仓库中的代码变更进行管理，避免了代码被随意修改，但拥有写权限的用户仍然可以在仓库内创建/删除分支或标签。久而久之，仓库中的分支和标签会越来越混乱。一个典型的例子就是仓库中会存在许多过期无用的分支，既影响日常的维护，也降低了研发效率。

使用分支标签评审模式，可以有效避免以上问题。即使是具有相应权限的用户也将不再能直接创建/删除分支和标签，而是转而创建一个评审，有效地将仓库内分支/标签的变更以评审的形式管理起来，达成管控诉求。新版代码评审对该能力进行了支持，具体请参考文档：分支标签评审模式

15. 开放性

15.1. OpenAPI

Codeup新版代码评审，开放了下入的OpenAPI：

• 创建代码评审

• 通过代码评审

• 更新代码评审

• 查询评审状态

• 查询代码评审列表

• 创建评论

• 更新评论

• 查询评论列表

• 查询代码评审设置

具体请参见文档：合并请求

15.2. WebHooks

Codeup新版代码评审，支持订阅多种类型的WebHook事件：

1. 创建事件

2. 更新事件

3. 评论事件

4. 合并事件

5. 表态事件

具体请参见文档：Webhooks设置

15.4. 关联类标（Labels）

Codeup提供了类标功能，类标可以作为一种特殊的标记关联到合并请求中，存在以下两种途径：

1. 在创建合并请求时，在"类标"字段选择你想关联的类标。

   

2. 在合并请求的详情页面，在右侧的类标区域，来选择类标关联或者删除已关联的类标。

   

同时，在合并请求的动态中也会记录关于类标的操作，如下图所示：

16. 类标在评审协作中的作用

16.1. 便于协作和沟通

在团队协作方面，类标可以提供明确的沟通途径和状态更新。当一个团队成员给合并请求分配一个“待复审”的类标时，其他人可以知道这个合并请求已经准备好由另一个成员进行复审。

16.2. 自动化和集成

通过使用类标的OpenAPI并且结合自动化工具，你可以自动化某些基于类标的操作，比如当合并请求获得特定类标时，自动启动部署或测试流程。

17. 合并请求列表页升级

17.1. 合并请求列表支持显示评审尺寸

在合并请求页面上，你可以直观地看到改动的大小。我们通过计算合并请求中的改动行数，并将其量化成5个级别，让用户能够一目了然地了解改动的规模。如下图所示：

新版的合并请求页面支持展示以下五个改动尺寸级别：

1. XS（小于10行）：这个级别适用于非常小的改动。它可能只是一行或几行代码的修改，或者是一个非常小的修复。

2. S（大于等于10行小于50行）：如果改动的行数在10到50行之间，它将被归类为S级别。这意味着它是一个中等大小的改动，可能是一个小功能的添加或一个简单的重构。

3. M（大于等于50行小于250行）：当改动的行数在50到250行之间时，它被认为是M级别的改动。这可能是一个较大的功能添加、一个模块的重构或一系列相关的改动。

4. L（大于等于250行小于1000行）：如果改动的行数在250到1000行之间，那么它属于L级别。这表示它是一个相当大的改动，可能涉及多个模块或子系统的修改。

5. XL（大于等于1000行）：如果改动的行数超过1000行，那么它被认为是XL级别的改动。这意味着它是一个非常大的改动，可能是一个全面的重构、一个新功能的完整实现或者是一个庞大的代码库的更新。

我们还通过将这五个级别的改动大小展示在图案中，帮助用户更好地了解改动的具体尺寸。当鼠标悬停在大小的图标上时，可以查看具体的尺寸。通过这五个级别的改动大小显示，你可以更好地评估合并请求的规模和复杂性。这将帮助你更好地了解改动的程度，并相应地进行资源分配和测试计划。

17.2. 根据多种维度对合并请求进行筛选

17.2.1. 根据类标进行筛选

产品示意图：

17.2.2. 根据评审类型进行筛选

产品示意图：

17.2.3. 根据发起人或评审人进行筛选

产品示意图：

18. 《小步快跑，高效协同—构建基于代码评审的研发工作流》直播视频

19. 总结

我们将为在云效codeup上所有进行研发工作的代码仓库免费升级到新版代码评审，目前我们新版CR正在逐步灰度中，欢迎各位开发者给我们提出宝贵的意见。