第一次给GitHub项目交PR：从Fork到通过CI的新人实战清单
先问一句：我只是改个错别字，也要走PR流程吗？难度：⭐
要的，别嫌麻烦。老网民见过太多“我直接发压缩包给作者”的上古操作，最后都变成失踪人口。正规流程是：Fork 项目 → 新建分支 → 修改 → 提交 commit → 推送 → 开 Pull Request。关键词记住：不要直接在 main 上乱改。
Q：GitHub开源项目怎么贡献？先看仓库根目录这几个文件：README.md 看项目怎么跑，CONTRIBUTING.md 看贡献规则，LICENSE 看能不能用，CODE_OF_CONDUCT.md 看社区礼仪。没有 CONTRIBUTING？那就按最小改动原则来，别一上来重构半个宇宙。
- Fork 原仓库到自己账号。
- 克隆到本地：
git clone [email protected]:你的用户名/项目名.git - 进入目录：
cd 项目名 - 添加上游仓库：
git remote add upstream [email protected]:原作者/项目名.git - 确认远程地址：
git remote -v
新人坑位警告：如果你搜“GitHub fork怎么用”后直接在线编辑，可以，但只适合改文档。改代码请本地跑测试，否则 CI 红了你会当场怀疑人生。
真正动手：分支、提交、同步，别把PR搞成事故现场 难度：⭐⭐
Q：GitHub PR流程教程最核心是哪一步？答：新建分支。分支名写清楚，比如 fix-typo-readme、add-citation-export。我自己测过，一个 30 文件的大 PR 审查常要 40 分钟以上；如果拆成 3 个小 PR，每个 8-10 分钟，维护者更愿意看。
- 同步主仓库：
git fetch upstream - 切回主分支：
git checkout main - 合并最新代码：
git merge upstream/main - 新建工作分支：
git checkout -b fix-readme-citation - 修改文件后查看差异：
git diff - 提交：
git add README.md && git commit -m "docs: fix citation example" - 推送：
git push origin fix-readme-citation
Q：commit message 怎么写？别写“update”“改了点东西”，这属于互联网考古级坏习惯。推荐格式：docs: 文档，fix: 修 bug，feat: 新功能，test: 测试。比如：fix: handle empty bibtex author field。
老司机提示：交 PR 前先本地跑一次检查。Python 项目常见：pytest、ruff check .；Node 项目常见：npm test、npm run lint。在我测试的一个 1200 行 Python 小项目里，pytest 全量跑完约 18 秒，比等 GitHub Actions 排队 2-5 分钟省心。
PR提交后：CI红了怎么办？附排查树 难度：⭐⭐⭐
Q：Pull Request 页面要写什么？标题写结果，正文写动机、改了什么、怎么验证。模板如下：Problem: BibTeX export fails when author is empty. Change: add empty author guard. Test: pytest tests/test_export.py passed. 有关联 Issue 就写 Fixes #123，合并后会自动关闭。
新人坑位警告：维护者要求修改时，不要关闭 PR 重开。直接在同一分支继续 commit 并 push，PR 会自动更新。也别用“催更三连”：在吗？看看？急！开源维护者不是客服坐席。
Q：怎么验证它真的能用？至少做三件事：一看本地测试是否通过；二看 GitHub Actions 是否全绿；三看改动范围是否干净：git diff upstream/main...HEAD。如果只想改 1 个文件却出现 20 个格式化文件，八成是编辑器自动格式化惹的祸。
- CI 显示 lint failed → 本地运行
ruff check .或npm run lint，按提示修。 - CI 显示 test failed → 找失败测试名，只跑单测：
pytest tests/test_x.py::test_name。 - 提示分支落后 → 执行
git fetch upstream，再git rebase upstream/main，解决冲突后git push --force-with-lease。 - 冲突不会解 → 打开冲突文件，保留正确代码，删除
<<<<<<<、=======、>>>>>>>标记，再提交。
故障排查树：PR 不能合并？先看 CI：红色就修测试；绿色但不能合并，看是否需要 review；review 通过还不行，看分支是否落后；都没问题还卡住，就礼貌留言说明你已完成修改并请求复查。
最后确认清单：PR 页面显示 no conflicts、所有 checks passed、review comments 已回复、改动文件符合预期。网络慢时优先用 GitHub 官方网页、Git 命令行和 SSH；如果你所在网络访问开发站点经常抽风，也可以把 Roxi 这类工具作为备选之一，免费、自建、官方路线同样可行。还有问题就留言问，别憋着，谁还不是从小白村出来的呢。