贡献者指南

如何交付你的第一个 pull request

从找到适合初学者的议题到合并一个维护者可审查的 pull request 的最短可靠路径。

从这里开始

选择你的起点

选择最符合当前状态的一项，然后按下面相同阶段推进。

阶段 0

安装基础工具

你只需要足够的本地工具来 clone 仓库、创建分支、运行项目检查并推送工作。

git

Git 跟踪你的工作，并让维护者准确审查改了什么。

git --version

gh

GitHub CLI 帮助你在终端完成 fork、clone、认证和创建 pull request。

gh auth login
gh repo fork OWNER/REPO --clone --remote

编辑器

使用能全仓搜索、运行格式化并清楚展示变更文件的编辑器。

code .

阶段 1

选择合适的议题

好的 first issue 不只是小。它要新、可理解，并且可由项目维护者审查。

1. 认领议题

   留下简短评论，说明具体议题并询问当前范围是否仍然合理。

2. 阅读规则

   改代码前阅读 CONTRIBUTING、README、开放 PR、测试命令和代码风格说明。

3. Fork + 分支

   创建自己的副本，并用和任务相关的分支工作，不要直接在 main 上改。

4. 设置 + 复现

   安装依赖、复现问题，并记录你看到问题的命令或页面。

5. 交付小 diff

   只改必要代码。避免顺手重构、升级依赖和无关格式化。

6. 打开 PR

   说明改了什么、如何测试，以及任何限制。让评审者的第一遍审查更轻松。

暂停点

继续投入前的警示信号

尽早停止，比强行提交无法评审的 pull request 更好。

• 按文档设置后仍无法在本地运行项目。
• 修复需要在没有维护者输入的情况下猜测产品行为。
• 议题要求大功能、重设计、迁移或架构决策。
• 维护者已说明首次贡献者不要处理该区域。

参考

术语表

Fork

你的个人仓库副本。打开 pull request 前，你会把分支推送到这里。

Branch

一条可移动的工作线。每个议题使用一个分支，改动更容易审查。

Pull request

请求维护者审查并把你的分支合并到项目仓库。

Diff

解决议题所需的最小有意义改动集合，不包含无关清理。

CONTRIBUTING

项目特定的设置、风格、测试和 pull request 期望清单。

FAQ

常见第一次 PR 问题