拉取请求审查系统
相关源文件
目的与范围
本文档提供了 Gitea Pull Request 评审系统的全面概述，该系统允许用户在合并之前协同评审代码更改、添加评论、批准更改或请求修改。该系统包括代码差异可视化、行内评论和评审工作流管理。
有关常规 Pull Request 管理（创建、合并等）的信息，请参阅 Issue 和 Pull Request。有关 Pull Request 的 CI/CD 集成信息，请参阅 Actions CI/CD 系统。
概述
Pull Request 评审系统是促进协同代码评审的关键组成部分，它通过以下方式实现：
- 可视化分支之间的代码更改
- 逐行内嵌评论
- 带有语法高亮的逐文件差异视图
- 评审状态跟踪（已查看文件、批准、更改请求）
- 评审摘要和讨论
来源
架构
高层架构
来源
核心组件
Pull Request 评审系统围绕几个协同工作的核心组件构建而成：
- Pull Request 控制器：处理与 Pull Request 及其评审相关的 HTTP 请求
- Git Diff 服务：生成和处理分支之间的 Git diff
- 评审模型：用于存储评审数据的结构体
- Diff 渲染系统：用于显示 diff 和收集反馈的 UI 组件
来源
Pull Request 评审流程
评审过程遵循以下步骤：
- 用户导航到 Pull Request 的文件视图
- 系统获取并显示基准分支和头部分支之间的差异
- 评审者可以：
- 查看文件更改
- 对特定行添加行内评论
- 标记文件为已查看
- 提交评审（批准、请求更改或评论）
来源
查看 Pull Request 文件
当用户访问 Pull Request 时，系统会：
- 加载 Pull Request 和 Issue 信息
- 获取基准分支和头部分支的提交数据
- 使用 git diff 服务生成 diff 信息
- 渲染带有语法高亮的 diff 视图
- 加载并显示行内评论
这方面的关键控制器函数是 ViewPullFiles，它负责准备和渲染 diff 视图。
来源
评审状态
Pull Request 评审可以有多种状态：
| 评审状态 | 描述 | 对 Pull Request 的影响 |
|---|
| 待处理 | 开始评审但未提交 | 无影响 |
| 评论 | 无批准/拒绝的通用反馈 | 无影响 |
| 已批准 | 更改已批准 | 可能满足合并要求 |
| 请求更改 | 合并前请求更改 | 如果需要，则阻止合并 |
| 已驳回 | 评审不再相关 | 无影响 |
来源
Diff 渲染系统
Diff 渲染系统负责：
- 生成提交之间的 diff 数据
- 处理 diff 以进行显示（语法高亮、行号）
- 处理各种文件类型（文本、二进制、图像）
- 提供在特定行添加评论的 UI
来源
代码高亮
系统使用语法高亮来提高代码 diff 的可读性
- 文件语言根据文件扩展名或内容进行检测
- 代码被拆分成行并由高亮器处理
- 高亮的代码将以正确的格式显示在 diff 视图中
GetComputedInlineDiffFor 函数计算 diff 行的 HTML 表示，高亮显示行内的特定更改，以便于识别。
来源
文件树导航
对于有多个文件更改的 Pull Request，系统提供了文件树视图
- 文件按路径组织成树形结构
- 用户可以导航到特定文件
- 树显示每个文件的添加/删除统计信息
- 文件可标记为已查看
来源
评审过程
用户可以对特定代码行添加行内评论
- 评论可以添加到添加或删除的行上
- 评论可以启动新线程或回复现有评论
- 评论支持 Markdown 格式
- 评论可以引用其他 Issue 和用户
来源
跟踪已查看文件
系统会跟踪评审者已查看的文件
- 文件可以标记为已查看/未查看
- 进度跟踪显示已评审的文件数量
- 自上次评审以来更改的文件会高亮显示
此功能有助于评审者在评审大型 Pull Request 时跟踪其进度。
来源
提交评审
评审完更改后，用户可以提交他们的评审
- 评审可以包含一个摘要评论
- 评审可以有状态（批准、请求更改、评论）
- 待定评论将随评审一起提交
来源
与 Git 集成
Pull Request 评审系统与 Git 紧密集成，以：
- 获取基准分支和头部分支的提交信息
- 生成提交之间的 diff
- 跟踪文件随时间的更改
- 显示 Pull Request 的提交历史
来源
权限与安全
该系统对 Pull Request 评审强制执行权限
- 存储库权限决定了谁可以查看/创建/评审 Pull Request
- 组织/团队权限可能适用额外的规则
- 分支保护规则可以在合并前要求进行评审
- 用户可以被指定为必需的评审者
来源
实施了几项优化，以高效处理大型 diff
- 对于非常大的更改，diff 会进行分页
- 文件内容按需加载
- 最大显示限制可防止浏览器过载
- 大型二进制文件会得到特殊处理
来源
结论
Pull Request 评审系统是 Gitea 协作开发工作流的关键组成部分。它提供了一套全面的工具，用于在合并前评审代码更改、讨论实现方案以及确保代码质量。该系统与 Gitea 的问题跟踪、git 操作和用户管理紧密集成，以提供无缝的代码评审体验。