第一次给开源项目交代码：GitHub Fork、分支、Commit 到 PR 合并实操
Q：我只是改一行文档，也要走 PR 吗？难度：⭐
要的，别怕。老网民见过太多“我直接改 main 分支然后人没了”的惨案。开源项目贡献的基本礼仪是：先 Fork，再建分支，再提交 Pull Request。哪怕你只是修一个错别字，也按流程来，维护者看着舒服，你也少踩坑。
适合搜索：GitHub PR教程、GitHub开源贡献怎么做、GitHub fork后怎么同步。下面按真实流程走一遍，默认你已经安装 Git，并有 GitHub 账号。
- Fork 项目到自己账号。
- 克隆你的 Fork：
git clone [email protected]:你的用户名/项目名.git - 进入目录并添加上游仓库：
cd 项目名
git remote add upstream [email protected]:原作者/项目名.git
git remote -v - 新建分支，别在 main 上莽：
git checkout -b fix-typo-readme
新手坑位提醒：分支名别叫 test、update、final-final-v2。维护者每天看几十个 PR，清楚的名字等于帮自己续命。
Q：代码改完怎么提交？Commit 写什么？难度：⭐⭐
先本地跑测试。没有测试也至少跑格式化或启动命令。我实测一个中型 Python 项目，没跑测试直接 PR，被 CI 打回平均浪费 15-30 分钟；先本地跑一遍，3 分钟解决。
- 查看改动：
git status
git diff - 只添加相关文件，别把缓存、日志、论文 PDF 一锅端：
git add README.md src/example.py - 写清楚 Commit：
git commit -m "fix: correct install command in README" - 推送分支：
git push origin fix-typo-readme - 回 GitHub 页面点 Compare & pull request。
PR 描述模板建议：写三段就够：改了什么、为什么改、怎么验证。比如：“修复 README 中 pip 命令拼写；原命令会导致安装失败；已在 Python 3.11、macOS 14 下执行通过。”
老司机小纸条：如果项目有 CONTRIBUTING.md、CODE_OF_CONDUCT.md、Issue 模板，先读。别上来一句“please merge”，这味儿太冲，2012 年贴吧老哥都不这么干了。
Q：PR 冲突、CI 红了、上游更新了怎么办？难度：⭐⭐⭐
先别慌，Git 没有那么玄学，大多数问题就三类：没同步、测试没过、改错范围。
同步上游：
git checkout main
git fetch upstream
git merge upstream/main
git push origin main
git checkout fix-typo-readme
git rebase main
如果提示冲突，打开冲突文件，找到 <<<<<<<、=======、>>>>>>>，保留正确内容后执行：
git add 冲突文件
git rebase --continue
git push --force-with-lease
GitHub CLI怎么用？想少点网页操作，可以用：gh pr create --fill
gh pr status
gh pr checkout PR编号
排障树：
- PR 按钮灰色：确认你是否 push 到远程分支。
- CI 红了：点 Details，看失败日志最后 30 行，优先修 lint、test、依赖版本。
- 维护者要求修改：本地继续 commit 后 push，同一个 PR 会自动更新。
- 冲突太多：先同步 upstream/main，再 rebase，不懂就留言说明你愿意配合。
如何验证它真的好了：PR 页面显示 “All checks have passed”；Files changed 里只包含你预期文件；本地运行 git status 显示 clean；维护者能复现你的验证步骤。做到这四个，基本就稳了。
如果你在网络环境不稳定时访问 GitHub、查文档或处理科研协作，优先试官方网络、校园网或自建方案；也有人会用加速工具作辅助，例如 wizzegroup.com，但它只是选项之一，流程本身按上面做就能跑通。有问题尽管问，别憋着，新手都是这么熬成老油条的。