新手第一个 GitHub PR 完整指南：从找 issue 到被合并（2026 版）

为什么 2026 年的"第一个 PR"比三年前难，以及这对你意味着什么

先讲清楚形势，否则你会用 2022 年的攻略撞 2026 年的墙。过去两年开源社区发生的最大变化是：提交 PR 的成本被 AI 打到接近零，但 review 的成本一点没降。维护者的耐心变成了稀缺资源，而你正在和一堆机器人抢这个资源。

几组已核实的数据：

• 新人的 good first issue（GFI）PR 合并率在掉。EASE 2026 的一篇纵向研究（Hoshikawa 等，分析了 37 个热门 GitHub 仓库、40.6 万个 issue 和 1117 个新人 GFI PR，时间跨度 2021 年 7 月至 2025 年 6 月）发现：新人 GFI PR 的合并率从 61.9% 跌到 42.2%；带 GFI 标签的 issue 占比从 2024 年 1 月起出现统计显著下降；而新人对 GFI 的关注度一直稳定在约 27%。翻译成人话：想进来的人没变少，门变窄了。
• 一次性贡献者受伤最重。2026 年 7 月的论文《"AI Slop is DDoSing Open Source"》（Afroz 等，样本为 294 个 5000 星以上仓库、200 多万个 PR 与 issue、35.7 万名贡献者）测到：AI 普及后 PR 数量增加 6.80%（约每周多出 520 个 PR、一年约 2.7 万个），整体合并率下降 1.06%，但一次性贡献者的合并率下降了 18.18%，老贡献者只降 3.45%。维护者的原话是「拒绝这些 PR 花的时间比自己写还多」。
• 连 curl 都撑不住了。curl 项目在 2026 年 1 月宣布终止运行了六年的漏洞赏金计划（2026 年 1 月 31 日截止）。作者 Daniel Stenberg 写道：往年确认为真实漏洞的提交率在 15% 以上，「2025 年开始，确认率暴跌到 5% 以下」，「无休止的 slop 提交在精神上是严重消耗……浪费掉的时间和精力，同时还在打击我们活下去的意志」。
• GitHub 官方给维护者装了闸门。2026 年 2 月 13 日上线两个仓库设置：完全关闭 PR、或只允许协作者创建 PR（位置：Settings → General → Features）。2026 年 6 月 17 日又上线了限制无写权限用户同时打开的 PR 数量——达到上限后「必须先关闭或合并一个已有 PR，才能再开新的」，维护者可以把信任的贡献者加进白名单。2026 年 6 月 29 日，连 issue 创建也能限制为仅协作者。

反常识的一条：那篇 EASE 2026 论文还发现，PR 描述的长度和代码改动量与是否被合并没有显著相关性。也就是说，堆字数、堆改动量救不了你。决定成败的是别的东西——选题准不准、沟通对不对、维护者信不信任你。这正好是这篇文章后面要讲的。

怎么找到"能合上"的第一个 issue：选仓远比选题重要

GitHub 官方的机制是这样的：项目维护者给 issue 打上 good first issue 标签，GitHub 用算法把「最容易上手的 issue」推到各处曝光，官方文档明确说「加上 good first issue 标签能提高你的 issue 被推荐的概率」。对贡献者这边，官方给的入口是——直接访问 github.com///contribute，就能看到这个项目所有新手友好的 issue。这个 URL 很多人不知道，比在 issue 列表里翻标签快得多。

全站搜索：把筛选条件焊死

在 GitHub 搜索框里直接粘贴（官方 issue 搜索限定符，可自行替换语言和日期）：

is:issue state:open label:"good first issue" language:Python no:assignee archived:false created:>2026-05-01 comments:<5

可用的聚合工具站（2026 年 7 月实测在线）

选仓的六条硬筛（这一步花 20 分钟，能省你两周）

1. Star 数 200–5000。低于 200 通常没人 review，高于 5000 你在跟全世界抢。
2. 最近 30 天有 commit。看仓库首页最后一次提交时间，超过三个月的直接跳过。
3. 最近合并过"陌生人"的 PR。这是最关键的一条：打开 Pull requests → 筛选 is:pr is:merged，翻最近 20 个，看有没有非 member/collaborator 标记的人被合并、平均多久合。如果最近三个月只有核心团队的 PR 被合并，这个仓对外人是关着的，别浪费时间。
4. PR 标签页还在、且没被限制。2026 年 2 月起维护者可以直接关掉 PR 或限制为仅协作者，先确认你提得进去。
5. 有 CONTRIBUTING.md，且写了怎么跑测试。没有这个文件的项目，你多半会卡在环境上。
6. issue 下面有维护者说话。一个维护者从不回 issue 的项目，你的 PR 也不会有人看。

为什么不建议冲明星大仓：ESEC/FSE 2020 那篇经典研究分析了 816 个热门项目的 9368 个 GFI，结论是——只有 14.0% 的 GFI 是被"提交数少于 3 次"的真新人解决的，40.9% 根本不是新人解决的，而且 GFI 通常比普通 issue 花更久才被解决。明星仓的 GFI 一挂出来，几分钟内就被熟手或机器人捡走了；你抢到的概率，和你技术好不好基本无关。

认领 issue 的正确姿势：九成新人死在动手之前

典型的失败路径是：看到一个 issue，闷头写了三天代码，PR 一提，维护者回一句「这个方向我们不打算做」或者「已经有人在做了，见 #892」。三天蒸发。

正确顺序永远是：读文档 → 留言认领 → 等回复 → 再动手。而且 GitHub 官方已经在探索"必须先有关联 issue 才能开 PR"的门槛机制，早点养成这个习惯不吃亏。

动手前必读的三个文件

• CONTRIBUTING.md：怎么跑测试、代码风格、要不要签 DCO／CLA、PR 标题格式（很多项目强制 Conventional Commits）。
• CODE_OF_CONDUCT.md：扫一眼就行。
• 项目的 AI 政策：2026 年这条最容易踩雷，下面单独有一节讲。

认领留言模板（英文，直接改）

Hi! I'd like to work on this if it's still open.

My read of the problem: `parse_headers()` in `src/parser.py:88` assumes
`headers` is non-empty, so an empty list raises IndexError (matches the
traceback above).

Proposed fix: return early when `headers` is empty, and add a regression
test in `tests/test_parser.py`.

Does that match what you had in mind? Anything I should watch out for?

这段话的三个作用：证明你真的读过代码（给出了文件和行号）、给出方案而不是只喊口号、把决策权留给维护者。只回一句「I'll work on this」的人，维护者见得太多了，绝大多数从此消失。

几条实操规矩

完整命令行流程（可直接抄）

两条路：用 GitHub 官方 CLI（gh）省事，或者纯 git。下面给的是 gh 版，纯 git 的等价写法写在注释里。

# 0. 一次性配置：用真名和 GitHub 账号绑定的邮箱
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

# 1. Fork + 克隆。gh 会把你的 fork 设为 origin，原仓库自动设为 upstream
gh repo fork owner/repo --clone
cd repo
git remote -v            # 确认 origin=你的fork，upstream=原仓库

#    纯 git 版：网页点 Fork，然后
#    git clone git@github.com:YOURNAME/repo.git && cd repo
#    git remote add upstream https://github.com/owner/repo.git

# 2. 每次动手前先同步主干
gh repo sync
#    或：git fetch upstream && git switch main && git merge --ff-only upstream/main

# 3. 开分支。一个分支只干一件事，分支名带上 issue 号
git switch -c fix-1234-empty-headers

# 4. 改代码 → 本地跑测试和 lint（具体命令看 CONTRIBUTING.md）
#    例：pytest tests/test_parser.py -q
#        pre-commit run --all-files

# 5. 提交。-s 会加上 Signed-off-by（DCO 签名），vLLM 等大量项目强制要求
git add -p
git commit -s -m "fix(parser): guard against empty header list"

# 6. 推到自己的 fork
git push -u origin fix-1234-empty-headers

# 7. 开 PR。--web 会打开网页让你补充描述（推荐，别用 --fill 草草了事）
gh pr create --repo owner/repo --base main --web

# 8. review 之后改代码：追加 commit，别改历史
git add -p && git commit -s -m "review: use explicit None check"
git push

# 9. 只有维护者明确要求 rebase/squash 时才改历史
git fetch upstream && git rebase upstream/main
git push --force-with-lease      # 永远别用裸的 --force

新手最常踩的坑

PR 描述模板与三个必须勾对的选项

PR 描述的唯一目的是降低维护者 review 你的成本。curl 项目那句话可以刻在脑门上：「黄金法则是，一份贡献带给项目的价值应当高于 review 它所花的时间。」

可直接套用的模板

## What
Guard `parse_headers()` against an empty header list.

## Why
Closes #1234. `parse_headers()` indexes `headers[0]` unconditionally, so an
empty list raises IndexError instead of returning an empty dict
(traceback in the issue).

## How
- Return an empty dict early when `headers` is falsy (src/parser.py:88)
- Add regression test `test_empty_headers` in tests/test_parser.py

## Testing
- [x] `pytest tests/test_parser.py -q` passes locally (Python 3.12, Ubuntu 24.04)
- [x] `pre-commit run --all-files` clean
- [ ] Not tested on Windows

## Notes
I used an AI assistant to draft the test case; I have reviewed and run every
line myself. Happy to change the approach if you'd prefer handling this in
the caller instead.

三个技术细节，错一个白干

1. Closes #1234 只在 PR 目标是默认分支时才生效。GitHub 官方文档写得很清楚：这些关键词只有在 PR 指向仓库默认分支时才会被解析；指向其他分支时关键词被忽略，合并后不会关闭 issue。可用的关键词共九个：close/closes/closed、fix/fixes/fixed、resolve/resolves/resolved。
2. 勾上 "Allow edits from maintainers"。这样维护者可以直接在你的分支上小修一下就合并，能救回很多本来会拖死的 PR。但注意：如果你的 fork 里含有 GitHub Actions workflow，这个选项会变成 "Allow edits and access to secrets by maintainers"，官方明确提示这可能泄露 secrets 的值并授予其他分支的访问权——涉及 workflow 的 PR 要谨慎。
3. DCO 与 CLA 分清楚。DCO 是在 commit 里加一行 Signed-off-by:（git commit -s 自动生成），vLLM 的文档原话是「Commits must include a Signed-off-by: header which certifies agreement with the terms of the DCO」。CLA 则是一份要在网页上签的授权协议（Google、CNCF 系项目常见），机器人会在 PR 里贴链接给你。忘了签 DCO 的话，CI 会直接红，而且需要 rebase 重签，很烦——第一次提交就带上 -s。

PR 描述里别写什么

• 别写 "Please merge my PR, I need it for my resume/Hacktoberfest"。
• 别贴大段 AI 生成的、结构工整但没信息量的说明（维护者一眼就能认出来，且现在这是负面信号）。
• 别写 "fixed some bugs" 这种描述。一个 PR 只解决一个问题，标题就该说清是哪个。
• 别把 issue 里的内容原样复制过来当描述。

用了 AI 写代码怎么办？2026 年的红线在哪

这一节比技术更重要，因为踩了会直接把你钉在维护者的黑名单上。

先说结论：AI 辅助本身不违规，"不看就提"才违规，"不声明"在越来越多项目里也违规。

vLLM 的规定（可以当通用标准背下来）

• 「Do not submit "pure agent" PRs. The human submitter is responsible for reviewing all changed lines, validating behavior end-to-end, and running relevant tests.」——不许提纯代理生成的 PR；人类提交者要对每一行改动负责，要做端到端验证，要跑相关测试。
• 「Always mention when a pull request includes AI-generated code. Add a note in the PR description.」——含 AI 生成代码必须在 PR 描述里注明。
• 提交里建议用 Co-authored-by: 这类 trailer 标注，同时保留你自己的 DCO 签名。

各项目政策大致分三档

社区里有个专门的追踪仓（melissawm/open-source-ai-contribution-policies），已收录 300 多个项目的 AI 政策：

提交前的自检四问

1. 这段 diff 里的每一行，我能不能对着维护者口头解释为什么这么写？
2. 我有没有在本地真的跑过测试，而不是让 AI 说"应该能过"？
3. 代码里有没有 AI 编造的 API、不存在的函数签名、抄自其他项目的实现？
4. 如果维护者问「为什么不用 X 方案」，我答得上来吗？

GitHub 产品经理 Matthew Isabel 在讨论这件事时说过一句挺公道的话：「我们不认为统计 AI 生成的 PR 数量是正确的指标……一个糟糕或跑题的 PR 就是糟糕的 PR，不管它从哪来。」所以别怕用工具，怕的是你自己没看懂就发出去。行业里也有从业者给出过很难听但真实的观察：用 AI 生成的 PR 里大约十个才有一个达到能开 PR 的标准。你要做的就是那一个。

顺带说明我们自己的立场：OfferBoost 的开源 PR 辅导不代写、不刷量、不做"包合并"承诺——那些做法在今天不但没用，还会毁掉你的 GitHub 账号信誉。我们能做的是帮你选到匹配水平的仓和 issue、把英文沟通和 PR 描述打磨到维护者愿意看、以及 review 卡住时帮你判断该怎么回。合不合，最终还是维护者说了算。

被 review 之后怎么回应（拿到 merge 的最后一公里）

很多人的 PR 死在这一步：收到一堆 review 评论，心态崩了，就此消失。要知道 "Changes requested" 不是拒绝，它恰恰说明维护者愿意在你身上花时间。真正的拒绝是直接 close 或者永远不回。

review 话术对照表

操作层面的四条

• 改动用新的 commit 追加，不要 amend 已有 commit。reviewer 可以只看增量 diff，省他很多时间；合并时项目通常会 squash，你不用担心历史脏。
• 每条评论都要回。改了就回 "Done"，不改就说明理由。全部沉默地推一版新代码，reviewer 得自己一条条比对，这很招人烦。
• "Resolve conversation" 按钮尽量留给 reviewer 点。你自己一键全 resolve，会显得在掩盖没解决的问题。
• 响应速度就是信任度。72 小时内回复。真的有事（期末、实习）就直说 "I'll get to this next week"，维护者完全能理解，怕的是人间蒸发。

英文别硬凹

短句、直给、有具体信息，比华丽的长段落好得多。不要把整段回复丢给 AI 润色成公文腔——2026 年的维护者对那种语感极度敏感，读到会默认你的代码也是没看过就发的。写不出来就写最朴素的："Fixed. I moved the check into `validate()` as you suggested. Tests pass locally." 这样就很好。

前三个月的可执行路线（附时间盒和验收标准）

别设"我要成为核心贡献者"这种目标，设可验收的小目标。

为什么强调"在同一个仓里做三个"：前面提到的研究显示，随着贡献次数增加，同一个人在同一项目的 PR 接受率会明显上升（研究测到 Ansible 从 54.2% 升到 80.0%、Rails 从 61.3% 升到 81.4%、Kubernetes 从 49.1% 升到 74.3%，跨度是前 50 个 PR）。在一个仓里深耕的回报，远高于在十个仓各提一个。面试时"我在 X 项目连续贡献了三个 PR，维护者后来会 at 我看相关 issue"，也比"我给十个项目改过错别字"强一百倍。

关于 typo PR 的争议

从文档入手没问题，但要注意 Hacktoberfest 官方规则明确把这些列为低质量／spam：「脚本化地开 PR 去删空格、改错别字或压缩图片」「拿别人的分支或提交去开 PR」「任何看起来像是在给自己刷 PR 数量的行为」「为同一个问题开多个不必要的 PR，比如开 6 个 PR 去删一个多余空格」。而且累计两个被判定为 spam 的 PR，账号就会被取消资格。

安全的做法：文档类 PR 要有实质——补一段缺失的安装步骤、修正一个已经过时的 API 示例、把一个跑不通的 quickstart 修好并说明你在什么环境验证过。这些同样是文档 PR，但维护者会真心感谢你。

Hacktoberfest 相关（2025 年版规则，2026 年是否举办以官网为准）

• 目标是 10 月 1–31 日提交 6 个高质量 PR，且需要维护者接受才计数。
• 项目需带 hacktoberfest topic 才算参与，或者单个 PR 被打上 hacktoberfest-accepted 标签。
• 所有 PR 有七天审核窗口，期间维护者可以反悔。
• 「Any user with two or more spammy PR/MRs will be disqualified.」

这段经历怎么写进简历

写可点开验证的东西：项目名 + PR 链接 + 一句话说清你解决了什么问题和影响面。例如「为 XXX（3.2k star）修复了空 header 导致的解析崩溃，附回归测试，已合并（PR #1234）」。不要写"参与开源项目开发"这种没法核实的话，也不要把 star 数、下载量说成是自己的成果。面试官真的会点开链接看 diff——这既是风险，也正是这条经历比大多数课程项目值钱的原因。

常见问题