如何创建你的第一个开源 PR

Good First Issue,
contributorsopen-sourcepull-requests

第一次开源 pull request 的难点通常不是 Git、GitHub，或创建 PR 的操作本身。真正难的是选择一个范围小、仍然有效、容易理解，并且有机会得到维护者 review 的任务。

Good First Issue 正是围绕这个判断构建的。它帮助你从“我想贡献”走到“这个 Issue 很现实，仓库仍然活跃，也有足够上下文让我提交一个有用的 PR”。

从合适的 Issue 开始

先打开 Issues 页面。用你熟悉的工具或技术关键词搜索，按标签或语言筛选，并通过排序避免从陈旧任务开始。

有用的入口包括：

不要把标签当成保证。它只是起点。一个好的 first issue 仍然需要清晰范围、活跃仓库，以及足够信息让你验证修改。

像 reviewer 一样阅读 Issue

在 clone 之前，先打开 Issue 详情页，查看它是否值得投入时间。关注标签、仓库、主要语言、stars、评论、反应、负责人、描述和 GitHub 源链接。

然后再看 Contributor Guide 元数据。Good First Issue 会总结技术栈、领域、Issue 类型、难度、预计时间、活跃状态、清晰度、前置条件、新手友好度和研究方向等信号。

你要寻找这些匹配点：

  • Issue 描述说明了成功结果。
  • 仓库近期仍有活动，review 有可能发生。
  • 所需技术栈接近你能在本地运行的范围。
  • 讨论里没有其他人已经深入处理同一个修复。
  • 研究方向给出了下一步，而不是模糊愿望。

GitHub 始终是事实来源。Good First Issue 索引并总结公开数据，但数据可能过期。如果 Issue 已关闭、已分配，或被 GitHub 上新的维护者评论推翻，请以 GitHub 为准。

选择很小的范围

第一次 PR 要优先考虑可 review 性。维护者应该能在几分钟内打开 diff 并理解变化。

好的第一步通常像这样：

  • 文档改进。
  • 能复现小型已知行为的测试。
  • 期望结果清楚的小 bug 修复。
  • 目标效果明显的 UI 打磨。
  • 你能验证的示例、README 或 setup 说明。

避免数据库 migration、认证、安全行为、发布自动化、依赖策略、公开 API、大范围产品功能或不清晰的产品决策。这些以后也可能是有价值的贡献，但因为 review 面太大，通常不适合作为第一个 PR。

写代码前先认领 Issue

当你有了小范围计划后，先在 GitHub Issue 留一条简短评论。你不是在请求开源贡献许可，而是在确认这个范围是否仍符合维护者期待。

Hi! I would like to work on this as my first contribution to the project.

My plan is to update <small, specific area> by <brief change>. Does that scope still make sense?

If there is already a preferred approach, I am happy to follow it.

如果维护者回复了建议，就按建议做。如果没人回复，但 Issue 明确 open 且无人分配，你也可以提交一个小而充分测试的 PR。保持 diff 狭窄，让维护者容易说 yes、no，或“请调整这一部分”。

Fork、建分支、测试并打开 PR

确定范围后，优先遵循仓库自己的贡献文档。如果没有指定流程，通常下面这版已经足够：

gh repo fork OWNER/REPO --clone
cd REPO
git checkout -b fix-small-specific-thing

# 使用项目文档指定的 package manager 安装依赖。
<install command>

# 做解决 Issue 的最小修改。

# 打开 PR 前运行相关检查。
<test command>

git status
git add <changed files>
git commit -m "fix: update small specific thing"
git push -u origin fix-small-specific-thing
gh pr create --fill

更完整的命令级流程可以参考 Contributor guide。

什么样的 PR 适合维护者 review

适合 review 的 PR 会说明改了什么、怎么测试，以及 reviewer 在看 diff 前需要知道的事项。你不需要写长文，但需要提供足够上下文，避免 reviewer 只能从代码里反推意图。

## What changed

- Updated <area> so <behavior/result>.
- Kept the change limited to <scope>.

## How I tested

- Ran <command>.
- Manually checked <page, flow, or example>.

## Notes

- This addresses <issue link>.
- I am new to this repository, so feedback on the preferred style is welcome.

PR 打开后继续关注维护者评论。用小的后续 commit 响应反馈，除非项目要求，否则避免 force push，并让讨论始终围绕合并这个具体 Issue。

准备选择下一次贡献时，回到 issues 或浏览 repositories，重复同样流程：先选择活跃、可理解、可 review 的工作，再开始写代码。