完全初学者
从工具、术语和一个只改文档的变更开始。目标是完成一次安全闭环。
贡献者指南
如何交付你的第一个 pull request
从找到适合初学者的议题到合并一个维护者可审查的 pull request 的最短可靠路径。
从这里开始
选择你的起点
把这些卡片当作静态选择器。选择最符合当前状态的一项，然后按下面相同阶段推进。
第一次 PR
选择一个很小且近期的议题，保持 diff 聚焦。编码前先确认范围。
再次贡献者
把这套流程当作清单，然后把主要精力放在复现和测试修复上。
阶段 0
安装基础工具
你只需要足够的本地工具来 clone 仓库、创建分支、运行项目检查并推送工作。
git
Git 跟踪你的工作，并让维护者准确审查改了什么。
git --versiongh
GitHub CLI 帮助你在终端完成 fork、clone、认证和创建 pull request。
gh auth login
gh repo fork OWNER/REPO --clone --remoteeditor
使用能全仓搜索、运行格式化并清楚展示变更文件的编辑器。
code .阶段 1
选择合适的议题
好的 first issue 不只是小。它要新、可理解，并且可由项目维护者审查。
好信号
- 议题较新，或有维护者回复。
- 仓库设置说明仍然可用。
- 期望改动能放进一个小 pull request。
- 描述了测试或手动验证步骤。
警示信号
- 已有多人在做同一个议题。
- 议题模糊、陈旧，或被设计讨论阻塞。
- 改动涉及安全、计费、数据库迁移或发布自动化。
- 项目近期没有维护者活动。
判断路径
- 你能用一句话说明这个请求吗？
- 你能在本地复现或验证问题吗？
- 改动能保持小且独立吗？
- 如果三项都是 yes，就询问是否可以接手。
阶段 2
6 步流程
保持流程简单可预期。小 pull request 更容易审查、修正和合并。
认领议题
留下简短评论，说明具体议题并询问当前范围是否仍然合理。
阅读规则
改代码前阅读 CONTRIBUTING、README、开放 PR、测试命令和代码风格说明。
Fork + 分支
创建自己的副本，并用和任务相关的分支工作，不要直接在 main 上改。
设置 + 复现
安装依赖、复现问题，并记录你看到问题的命令或页面。
交付小 diff
只改必要代码。避免顺手重构、升级依赖和无关格式化。
打开 PR
说明改了什么、如何测试，以及任何限制。让评审者的第一遍审查更轻松。
gh repo fork OWNER/REPO --clone --remote
cd REPO
git checkout -b docs/fix-install-note
pnpm install
pnpm test
git status
gh pr create --fill模板
可复制模板
根据实际情况调整措辞，保持具体，不要承诺超出你能完成的范围。
认领评论
你好！我想处理这个 issue。
我的计划是把改动范围控制在：
- ...
在开始前，这个方向是否合适？PR 描述
## 改动内容
- ...
## 如何测试
- ...
## 备注
- 这是我对该仓库的第一次贡献，欢迎反馈。暂停点
继续投入前的警示信号
尽早停止，比强行提交无法评审的 pull request 更好。
- 按文档设置后仍无法在本地运行项目。
- 修复需要在没有维护者输入的情况下猜测产品行为。
- 议题要求大功能、重设计、迁移或架构决策。
- 维护者已说明首次贡献者不要处理该区域。
参考
术语表
- Fork
- 你的个人仓库副本。打开 pull request 前，你会把分支推送到这里。
- Branch
- 一条可移动的工作线。每个议题使用一个分支，改动更容易审查。
- Pull request
- 请求维护者审查并把你的分支合并到项目仓库。
- Diff
- 解决议题所需的最小有意义改动集合，不包含无关清理。
- CONTRIBUTING
- 项目特定的设置、风格、测试和 pull request 期望清单。
FAQ
常见第一次 PR 问题
维护者一周没回复怎么办？
用简短跟进说明当前状态并提出一个直接问题。如果仍没有回复，换一个议题，不要无限等待。
设置失败时我该怎么办？
说明你尝试了什么，贴出准确错误，附上操作系统和工具版本，并询问下一步调试方向。
我的第一个 PR 可以只改文档吗？
可以，前提是仓库欢迎文档改动。清晰文档、示例、错字和坏链修复都是真正的贡献。
第一次合并之后
把一次贡献变成可重复的习惯
感谢评审者，记录有效命令，保存项目约定，然后寻找只比上一个稍难一点的下一个议题。