Pull Request 的魔法

1. 从合并到提案：为什么需要 Pull Request？

在上一讲中，我们学会了在本地计算机上合并（merge）分支。这在你单独工作时非常有效。但如果是整个团队在协作开发呢？如果每个人都把自己的更改直接合并到主分支 main，很快就会出现混乱：有人可能不小心加入有错误的代码、破坏构建，或删除同事工作中的重要部分。

为避免这种情况，团队协作采用另一种方法。不是立刻合并更改，而是先创建合并提案。这种提案称为 Pull Request（简称 PR），在某些平台上称为 Merge Request。

Pull Request 是一项正式请求：“请从我的分支拉取（pull）我的更改，并将它们合并（merge）到主分支”。但它不仅仅是请求，更是一个在代码进入 main 之前进行讨论、审查与改进的平台。

2. 使用 Pull Request 的标准工作流程

让我们按步骤看看，在创建新功能时通常的工作流程是什么样的。

在为新任务创建分支之前，请确保你已推送所有已完成的提交（push），并更新（Update Project）主分支 main。

否则，你在 main 中那些“遗忘”的本地提交会不小心被带入新的 Pull Request，给同事造成混淆。

步骤 1. 为新任务创建分支。

如同以往，任何新工作都应从创建独立分支开始。假设我们想在项目中添加一份贡献指南文件。创建分支 feature/add-contribution-guide。

步骤 2. 做出更改并将你的分支推送到 GitHub。

在新分支中创建文件 CONTRIBUTING.md（创建后点击 Add），并写一段给其他开发者的说明。随后使用带有清晰信息的 Commit and Push，例如：docs: Add contribution guide。

这是关键一步！Pull Request 是基于已经存在于远程服务器上的分支创建的。因此，在创建 PR 之前，务必先将你的新分支推送（push）到 GitHub。

3. 在 IntelliJ IDEA 中创建 Pull Request

现在你的分支已经在 GitHub 上了，可以创建 Pull Request 了。

步骤 1. 打开 Pull Requests 选项卡。

IDE 左侧有一个 Pull Requests 选项卡。打开它并点击 + 图标以创建新的 PR。

步骤 2. 填写 PR 信息。

IDE 会自动打开一个便捷的界面帮助你创建 Pull Request。你的任务是把它正确填写。让我们看看主要字段：

1. 标题：IDE 往往会把分支名直接填进来，但这不是好实践。标题应简洁、清晰，并能体现变更的本质，就像一条好的提交信息。
2. 描述：在这里解释你做了什么以及为什么要这么做。
3. 审查者（Reviewers）：在这里选择一位或多位需要审查你代码的同事。在教学项目中可以跳过，但在实际工作中这是必需的。
4. 负责者（Assignees）：通常填写你自己。这意味着你是作者，也是该任务的主要责任人，并负责在审查后进行修改。

当所有字段都填写完毕后，直接点击 Create Pull Request。

4. 代码审查：检查与讨论

创建 PR 后，最重要的阶段开始了——代码审查（code review）。你的同事可以打开你的 PR，查看所有更改并留下评论。

你可以在 IDE 的 Pull Requests 选项卡中直接查看所有讨论。如果有人留下了评论，你会收到通知。

如果被要求修改怎么办？

非常简单！无需创建新的 PR。只需在同一个分支上对代码做出必要修改，创建新的提交并推送（push）。GitHub 上的 Pull Request 会自动更新，添加你的新提交。

5. 完成工作：合并并删除分支

当所有意见都已修复且团队批准了你的更改后，就可以合并 Pull Request。通常由高级开发者操作；如果你有权限，也可以自己完成。

步骤 1. 合并（Merge）

合并通常在 GitHub 网站上进行。在你的 PR 下会出现一个大的绿色按钮 Merge pull request。点击后，你的代码将成为主分支 main 的一部分。

步骤 2. 删除分支。

合并后，你的 `feature` 分支已不再需要，应将其删除以免弄乱仓库。GitHub 会主动给出该建议，显示 Delete branch 按钮。

别忘了也要在 IDE 中删除本地分支副本，以保持整洁。这可以通过同一个分支管理菜单完成。

6. 三条提交规则

一次好的提交不仅要有合适的信息，还要有合理的内容。为了让你的变更历史干净、有用且专业，请遵循三条简单规则。

规则 1：按约定编写清晰的提交信息

你的提交是你发送给团队以及未来自己的消息。充斥着“fix”或“update”等信息的历史毫无用处。最流行的规范叫做 Conventional Commits。它建议如下结构：

<tip>: <kratkoe opisanie>

类型是用来描述你变更类别的简短词语：

• feat: (feature) —— 用于新增功能。
• fix: —— 用于修复缺陷。
• docs: —— 用于文档变更。
• style: —— 用于格式化修改，不影响代码逻辑。
• refactor: —— 用于代码重构，不增加新功能也不修复缺陷。
• test: —— 用于新增或修复测试。
• chore: —— 用于与代码无直接关系的日常任务（更新依赖、构建配置等）。

示例：

• 不佳： fixed bug
• 良好： fix: Correct user login validation

• 不佳： readme
• 良好： docs: Update installation instructions

规则 2：一次提交——一个逻辑变更（原子性）

不要试图在一次提交里同时包含缺陷修复、新功能添加和旧代码重构。这样的提交非常难以审查，如果出现问题也几乎无法无痛回滚。

每次提交只应解决一个具体问题。

• 不佳： 一个提交信息为 “Update user page” 的提交，同时添加头像字段、修复用户名校验错误并修改按钮颜色。
• 良好： 三个不同的提交：
  1. feat: Add avatar upload to user profile
  2. fix: Correct username validation logic
  3. style: Update button colors on user page

小而聚焦的提交更容易理解与管理。

规则 3：提交不应破坏项目

主分支中的每一次提交都应让项目保持可用。在提交之前，你至少要确保代码能够编译。但如何确保你没有不经意间破坏系统的其他部分呢？仅依赖手动检查是有风险的。

这时就需要自动化。本课程不会配置自动化流程，但你应当了解它在真实项目中的工作方式。现代团队使用持续集成（Continuous Integration，CI）系统，例如 GitHub Actions。

它如何工作？

你编写代码并为其编写测试。然后在 GitHub 上配置一个工作流（workflow）。现在，只要你向 Pull Request 推送（push），魔法就发生了：

1. GitHub Actions 监听到该事件并触发你的工作流。
2. 它会自动“构建”项目并运行所有测试。
3. 如果所有测试都通过，GitHub 上你的提交旁会出现绿色对勾。这向整个团队表明你的更改是安全的。
4. 如果有任意一个测试失败，你会看到红色叉号。严禁将这样的 PR 合并到主分支。

            graph LR
            subgraph GitHub
            A[开发者] -- "push" --> B(仓库)
            B -- "事件: push" --> C{GitHub Actions}
            end

            subgraph Workflow
            C -- "启动" --> D[运行_测试]
            D --> E[成功]
            D --> F[失败]
            end

            subgraph Notifications
            F --> G((Email))
            G --> H[开发者]
            G --> I[团队]
            end

            style F fill:#f99,stroke:#333,stroke-width:2px
            style G fill:#ccf,stroke:#333,stroke-width:2px
        

可以配置通知。如果测试失败，GitHub Actions 可以向你或整个团队发送邮件。这种方式塑造了一种文化：测试不是简单的形式，而是开发不可分割的一部分，每个人都对自己的代码质量负责。