GitHub Pull Request：设计与使用

概览

前置认知：PR 是给谁用的？

在正式学"PR 是什么"之前，先破除一个常见误解——很多人以为 PR 是"留给团队以外的人"用的（比如开源项目里路人给项目贡献代码）。这是只看到了一半。PR 的真实定位是：所有"代码合入前需要审查"的场景的通用机制——团队内外都在用，而且团队内部用得更频繁。

PR 的核心作用一句话：在代码正式合入主分支之前，先让别人看一眼、讨论一下、确认没问题再合。至于"别人"是谁——团队内外都可能是。它要回答的问题不是"谁有资格提代码"，而是"这行代码凭什么能进 main"。

• 代码审查（Code Review）：同事帮你检查 bug、风格、设计问题——多一双眼睛，少一堆线上事故
• 留下讨论记录：为什么这么改、权衡了什么，都留在 PR 评论里，半年后还能查
• 触发 CI 自动测试：PR 一开，自动跑测试，绿了才合——把"能跑"从口头承诺变成机器把关
• 保护主分支：谁也不能直接往 main 上推，必须经过 PR 这道门

• 外部人没有仓库写权限，不能直接推代码
• 路径：fork（复制仓库到自己账号）→ 在自己仓库改 → 向原仓库发 PR → 维护者审查后决定 合并 / 要求修改 / 拒绝
• 这就是你向 SWE-bench 这类上游项目贡献代码时走的路

出处：GitHub Docs · About pull requests 与 Creating a pull request。

§ 1 什么是 PR：一个"请你 pull 我的代码"的请求

Pull Request（PR） 的字面意思就是"拉取请求"——你（贡献者）告诉项目维护者："请把我在 X 分支上的改动拉（pull）到主分支"。

1. 源分支（base / head）：你想把哪个分支的改动合到哪个分支
2. 一组 commits：你做的代码改动（按时间顺序排列）
3. 讨论 + 审批：维护者可以在你的改动上逐行评论，最终决定 merge / close

# PR 在 Git 层面是什么？
# 假设你想把 feature-branch 合并到 main：

# 1. 你推 feature-branch 到 remote
git push origin feature-branch

# 2. PR 触发后，GitHub 帮维护者做的事：
#    · 计算 feature-branch 和 main 的差异（git diff main..feature-branch）
#    · 展示 commits 列表（git log main..feature-branch --oneline）
#    · 维护者点击"Merge pull request" → 等价于：
git checkout main
git merge --no-ff feature-branch   # --no-ff 保留 PR 合并的拓扑

# 3. PR 的"价值"不在 git 命令（merge 谁都会），
#    而在 PR 流程（review / checks / conversation）——这些是 GitHub 加的协作层

§ 2 PR 的 7 个组件

一个完整的 PR 包含 7 个组件——每个都有明确作用。

§ 3 PR 完整生命周期

PR 从创建到关闭，经历 5 个状态——可以无限循环在第 3-4 步（review 反复打回）。

┌──────────────────────────────────────────────────────────────────┐
│  1. Draft（草稿）                                                  │
│  →  开发者创建 PR，但标记为 Draft（"还在做，别 review"）          │
│  →  通常用于 WIP（work in progress）——CI 可以跑但不被 merge     │
│  →  想跟别人提前讨论，但不是"请 review"                            │
└──────────────────────────────────────────────────────────────────┘
                              ↓ （标为 "Ready for review"）
┌──────────────────────────────────────────────────────────────────┐
│  2. Open（开放）                                                   │
│  →  PR 正式进入 review 阶段                                       │
│  →  通知 reviewer（@mention / 自动指派）                          │
│  →  CI 自动触发（GitHub Actions 跑测试）                         │
└──────────────────────────────────────────────────────────────────┘
                              ↓ （reviewer 提评论 / 打回）
┌──────────────────────────────────────────────────────────────────┐
│  3. Review（评审）—— 可能多轮                                     │
│  →  Reviewer 提 comments（提问 / 建议 / 必改）                     │
│  →  开发者 push 新 commit 响应评论                                │
│  →  Reviewer 改评论状态：approve / request changes / comment      │
│  →  CI 重新跑（验证新 commit 没破）                                │
│  →  ↻ 循环直到所有 reviewer approve（或 maintainer 强 merge）    │
└──────────────────────────────────────────────────────────────────┘
                              ↓ （所有阻塞条件解除）
┌──────────────────────────────────────────────────────────────────┐
│  4. Approved（已批准）                                              │
│  →  达到合并条件：required reviews 数通过 + CI 全部绿              │
│  →  Maintainer 点击 "Merge pull request"                          │
└──────────────────────────────────────────────────────────────────┘
                              ↓
┌──────────────────────────────────────────────────────────────────┐
│  5. Merged（已合并）/ Closed（关闭）                                │
│  →  Merged：PR 合到目标分支——完成                                │
│  →  Closed：PR 没合（被拒绝 / 弃用 / 改用其他方式）——关闭        │
└──────────────────────────────────────────────────────────────────┘

§ 4 PR 的 4 个关键概念（必须分清）

§ 5 PR 最佳实践（写 PR 的 6 条铁律）

提一个"让人愿意 review"的 PR，是工程基本功。下面 6 条铁律，新手老手都适用。

1. 小而专注：一个 PR 只做一件事——修一个 bug / 加一个 feature / 重构一个模块。PR 改的代码行数 < 400 行，超过 800 行的 PR 几乎一定会被 reject（"拆成几个 PR"）
2. Title 写清"做了什么"：动词 + 范围 + 简短说明
   · 好："Fix: handle None gracefully in user lookup"
   · 差："fix stuff" / "update code" / "WIP"
3. Description 写清"为什么 + 怎么做的"：4 段式
   · What：改了什么
   · Why：为什么改（issue 链接）
   · How：怎么改的（思路 / 关键决策）
   · Test：怎么测试的
4. 关联 issue：用 fixes #123 关键字——PR merge 后自动关 issue
5. Draft for WIP：还在做时用 Draft——不要让 reviewer 看半成品
6. 响应评论要快：reviewer 等你回 comment 的时间越长，PR 越容易"stale"被关

## What
Fix the bug where `get_user()` raises AttributeError when user.email is None.

## Why
Issue #1234 reported that some users (registered via social login) have
no email set, causing the user dashboard to crash.

## How
- Add `is not None` check before accessing `.email`
- Add unit test for the None case
- Update docstring to document the new behavior

## Test
- All existing tests pass
- New test `test_get_user_with_no_email` passes
- Manual test on staging: dashboard no longer crashes

Closes #1234

§ 6 PR vs Merge Request（GitLab / Gitea 术语）

不同平台叫法不同，本质完全一样。

§ 7 PR 为什么是 SWE-bench 题目源

这一节是核心——把"PR 流程"和"SWE-bench 题目构造"打通。先对齐名词：SWE-bench（SWE = Software Engineering，软件工程；bench = benchmark，基准测试）是"用真实 GitHub issue 评测代码 agent"的软件工程基准，本教学平台的评测主线（详见 SWE-bench 入门）。

                GitHub Issue + PR
                ┌──────────────────────────────────────┐
                │  Issue: 标题 + body（问题描述）        │
                │  PR:    title + description + commits  │
                │         + diff + review + checks      │
                │         + conversation               │
                └──────────────────────────────────────┘
                              ↓ 提取
                ┌──────────────────────────────────────┐
                │  SWE-bench Instance（一条）            │
                │  instance_id:      "repo__issue-1234" │
                │  repo:             "django/django"     │
                │  base_commit:      PR merge base SHA  │
                │  problem_statement: issue body        │
                │  patch:            PR diff             │
                │  test_patch:       PR 引入的测试改动  │
                │  fail_to_pass:     新引入的失败测试    │
                │  pass_to_pass:     回归测试集          │
                └──────────────────────────────────────┘

引用与配套资料