综合练习

这一课你将能做到

1. 独立完成一次完整的 Fork + PR 开源贡献流程
2. 把前 11 课学到的所有命令、流程、规范串联成一次真实交付
3. 在真实项目（本站 java-nav）上留下你的第一个 GitHub 贡献记录

为什么要学

前面 11 课都是「分解动作」，这一课是「连贯动作」。就像学开车：科目二练倒车入库，科目三练上路。真正的掌握，是在一个真实项目里从头到尾走通一次完整流程——从发现 Issue 到代码合并进主干。

完成本课练习后，你的 GitHub 主页会多一条绿色贡献记录，你的简历可以写「参与过开源项目贡献」。

先建立图像

完整任务流程图：

发现任务              搭建环境              开发交付
   │                    │                    │
   ▼                    ▼                    ▼
浏览 Issues   →   Fork + Clone   →   开分支写代码
   │                    │                    │
   │                    │                    ▼
   │                    │               本地测试通过
   │                    │                    │
   │                    │                    ▼
   │                    │               提交 + push
   │                    │                    │
   │                    │                    ▼
   │                    │              创建 PR
   │                    │                    │
   ▼                    ▼                    ▼
              审查 → 修改 → 合并 → 庆祝 🎉

跟着做

本次练习任务：为本站 java-nav 项目提交一个真实 PR（可以是修复 typo、补充文档、改进样式、或解决一个 good first issue）。

步骤 1：找到合适的任务

打开本站 GitHub 仓库的 Issues 页面，筛选 label:"good first issue" 的任务。如果没有，可以：

• 修复一个错别字（docs 标签）
• 补充某个课程的 README 说明
• 改进某段 CSS 样式

步骤 2：Fork 仓库

访问本站仓库页面，点击右上角 Fork。完成后你账号下会出现 你的用户名/java-nav。

步骤 3：Clone 到本地

git clone git@github.com:你的用户名/java-nav.git
cd java-nav
git remote add upstream git@github.com:官方org/java-nav.git
git remote -v
# origin    git@github.com:你的用户名/java-nav.git
# upstream  git@github.com:官方org/java-nav.git

步骤 4：同步上游最新代码

git fetch upstream
git switch main
git merge upstream/main
git push origin main

确保你的 main 和官方保持一致，避免后续冲突。

步骤 5：创建功能分支

根据任务类型选择分支前缀：

# 假设你选择了修复 #15 这个 Issue：课程 README 错别字
git switch -c docs/fix-readme-typo

步骤 6：本地开发

打开项目，按照仓库根目录的 README 指引启动本地服务（通常是 mvn spring-boot:run 或 ./mvnw spring-boot:run），确认改动生效。

编辑文件，比如修正 content/课程/xxx/README.md 里的错别字。

步骤 7：小步提交

git status
git add content/课程/xxx/README.md
git commit -m "docs(课程): 修正 xxx 课程 README 错别字"

如果改动较多，分多个 commit：

git commit -m "docs(课程): 修正 xxx README 第一处错别字"
git commit -m "docs(课程): 补充 xxx README 缺失的示例代码"

步骤 8：推送并创建 PR

git push -u origin docs/fix-readme-typo

打开你的 Fork 仓库页面，点击「Compare & pull request」，按模板填写：

## 改动动机
Closes #15
课程 xxx 的 README 中存在 2 处错别字，影响阅读体验。

## 做了什么
- 修正第 12 行「路经」→「路径」
- 修正第 34 行「配值」→「配置」
- 顺手补全了第 50 行缺失的代码示例

## 怎么验证
1. 打开 content/课程/xxx/README.md 查看改动
2. 本地启动项目访问 /courses/xxx 页面确认渲染正常

## 截图
[贴改动前后对比截图]

步骤 9：响应审查意见

维护者可能会评论：

• 「第 34 行建议改成 xxx」
• 「能否补一个单元测试」
• 「commit message 格式请遵循规范」

礼貌回复、按需修改、推送更新，直到 PR 被 Approve 并 Merge。

步骤 10：清理本地环境

git switch main
git pull upstream main
git push origin main                 # 同步到自己的 Fork
git branch -d docs/fix-readme-typo
git push origin --delete docs/fix-readme-typo

讲清楚要点

1. 第一次贡献选「低风险任务」：typo 修复、文档补充是最佳入门，建立信心后再挑战功能开发。
2. 完整走一遍流程比完美更重要：哪怕只是改一个错别字，走完 Fork → PR → Merge 全流程就达到本课目标。
3. PR 合并后你的 GitHub 主页会亮起绿点：这是你开源足迹的开始，持续贡献会形成漂亮的贡献热力图。
4. 被拒绝也没关系：开源社区拒绝 PR 是常态，重要的是从反馈中学到东西。
5. 本站鼓励学员贡献：java-nav 项目本身就是教学项目，维护者对学员 PR 会非常友好。

你可能会懵的地方

• 我找不到 good first issue 怎么办？ 主动创造：阅读本站课程内容时发现的错别字、过时截图、不清晰的描述，都是合法的 Issue 和 PR 素材。

• 我的 PR 一直没被 review 怎么办？ 礼貌在 PR 下评论一句「请问方便 review 一下吗？谢谢！」，或者在社区群提醒。超过一周可以关闭重发。

• 改完代码本地跑不起来，能提 PR 吗？ 不能。PR 前必须确保本地能跑通。卡住了先在 Issue 区提问，或在 PR 描述里说明「本地启动失败，求助」并标记为 Draft。

• 我应该提几个 PR？ 本课要求至少 1 个合并成功的 PR。有余力可以做 2-3 个，覆盖不同类型（docs / fix / style）。

• 合并后能写进简历吗？ 当然。「参与开源项目 java-nav 贡献，提交 N 个 PR 并被合并」是真实的开源经历。

错法对照

错法	问题	正解
一次 PR 改 10 个文件	审查无法聚焦	一个 PR 只做一件事
PR 描述空白	审查者无从下手	按模板填动机/改动/验证
不本地测试就提 PR	CI 失败被打回	本地跑通再提
直接在 main 上改	同步上游时冲突	永远开功能分支
PR 合并后不删分支	仓库分支混乱	合并后立即清理

卡点急救

1. 本地启动项目报错：仔细阅读仓库 README，确认 JDK 版本、依赖安装步骤。卡住就在 Issue 区提问（附上完整错误日志）。
2. PR 提示冲突：git fetch upstream && git merge upstream/main，本地解决冲突后 push。
3. 维护者要求修改但改不动：诚实回复「这部分超出我目前能力，能否指点一下方向？」维护者通常会给出提示或亲自接手。

面试常问

• 你有开源贡献经历吗？ 拿出本课的 PR：「我为 java-nav 项目提交过 N 个 PR，主要负责 xxx。过程中学会了 Fork 工作流、PR 协作、Code Review 响应」。

• 描述一次你处理 PR 冲突的经历？ 讲一个真实场景：「我在提 PR 期间上游合入了新代码导致冲突，我通过 fetch upstream + merge 本地解决，并补充了相关测试用例」。

• 你怎么看待 Code Review？ 「双向学习的机会。我的 PR 被审查时学到了规范，审查别人 PR 时学到了不同思路」。

自测三问

1. 完整的 Fork + PR 流程包含哪几个关键步骤？
2. 为什么第一次开源贡献建议从 typo 修复开始？
3. PR 合并后还需要做哪些清理工作？

小结一句话

学完 11 课只是起点，完成一次真实的开源贡献，你才真正「会用 Git」。

延伸

• GitHub 文档：如何为开源做贡献
• 下一站：git-github-essentials track，深入 rebase、Hooks、CI/CD 集成。也可以去挑战 /roadmaps/git-github-essentials 路线图节点。