GitHub Flow 协作全流程：从 Fork 到发起 Pull Request (PR)

在 GitHub 上参与开源项目、向公共库贡献功能修复，或者在团队内部进行规范的代码协同开发时，Pull Request（简称 PR） 是最核心的工作模式。

许多新手开发者虽然熟悉单人开发下的 git push，但在尝试向他人仓库贡献代码时，常因为不清楚 Fork、Upstream（上游） 和 分支隔离 的概念，导致提交被拒或发生合并冲突。

本教程将以标准规范的 GitHub Flow 工作流为核心，带你从零完成一次标准的开源贡献与 PR 全流程。

一、GitHub Flow 核心流程概览

一个规范的 PR 流程遵循以下 6 个标准阶段：

[官方开源仓库 (Upstream)] 
       │ 1. 点击 Fork
       ▼
[你的个人远程仓库 (Origin)]
       │ 2. git clone
       ▼
[本地开发环境 (Local)] ── 3. 创建特性分支 (Feature Branch)
       │                  4. 编写代码并 Commit
       ▼
[推送特性分支到 Origin] ── 5. 在 GitHub 页面发起 Pull Request
       │
       ▼
[官方仓库 Maintainer 审查] ── 6. 审查通过并合并 (Merged)！

二、从 0 到 1 发起 PR 手把手实战

步骤 1：Fork 目标仓库到你的个人账号

浏览器打开你想要贡献的开源项目主页（例如 https://github.com/example/awesome-project）。
点击页面右上角的 Fork 按钮。
在弹出的窗口中，选择你的个人命名空间，取消勾选 Copy the main branch only（通常建议克隆完整分支以便查看历史），点击 Create fork。
几秒钟后，GitHub 会在你的个人名下生成一个完全独立的镜像副本（例如 https://github.com/your-username/awesome-project）。

步骤 2：克隆仓库到本地并配置上游源 (Upstream)

克隆你 Fork 后的个人仓库到本地：
```
git clone https://github.com/your-username/awesome-project.git
cd awesome-project
```
加速提示：若拉取大型开源仓库遇到连接慢，可借助 GH-Proxy 加速： git clone https://gh-proxy.com/https://github.com/your-username/awesome-project.git

查看当前配置的远程仓库地址：

git remote -v

此时通常只看到 origin 指向你的个人仓库：

origin  https://github.com/your-username/awesome-project.git (fetch)
origin  https://github.com/your-username/awesome-project.git (push)

关键操作：添加官方主仓库作为 upstream（上游源），用于后续同步官方最新代码：
```
git remote add upstream https://github.com/example/awesome-project.git
```
再次执行 git remote -v，即可看到同时拥有 origin（个人可写）与 upstream（官方只读）两个远程仓库。

步骤 3：创建独立的特性分支 (Feature Branch)

铁律：永远不要直接在 main 或 master 分支上直接修改并提交代码！保持本地主分支与官方上游完全纯净，所有新功能和 Bug 修复必须在独立分支上进行。

# 确保当前基于最新的 main 分支
git checkout main

# 创建并切换到新分支（命名清晰：如 feat/xxx、fix/xxx）
git checkout -b fix/dark-mode-crash

步骤 4：编写代码与规范化 Commit 提交

完成代码编写、通过本地单元测试后，进行暂存与提交：

# 查看改动文件
git status

# 暂存需要提交的文件
git add src/theme.js

# 提交改动（遵循 Conventional Commits 规范）
git commit -m "fix(theme): prevent null pointer exception on dark mode toggle"

Commit Message 建议格式：

feat: 增加新功能

fix: 修复 Bug

docs: 仅修改文档

style: 代码格式变动（不影响运行逻辑）

refactor: 重构代码

test: 新增或修改测试用例

步骤 5：推送分支到个人远程仓库

将本地特性分支推送到个人 GitHub 仓库（origin）：

git push -u origin fix/dark-mode-crash

步骤 6：在 GitHub 上正式发起 Pull Request (PR)

打开 GitHub 个人仓库主页，或者原作者官方仓库主页。
页面顶部通常会自动弹出浅黄色的高亮横幅：fix/dark-mode-crash had recent pushes，点击旁边的绿色按钮 Compare & pull request。
仔细核对分支对比方向：
- base repository：example/awesome-project（官方主库） -> base: main
- head repository：your-username/awesome-project（你的库） -> compare: fix/dark-mode-crash
填写 PR 标题与正文：
- 清晰描述修改的目的、解决的 Issue（如 Fixes #123，GitHub 会在 PR 合并时自动关联关闭该 Issue）；
- 如果项目有 PR Template，请严格遵循开源项目的清单要求。
点击 Create pull request 提交。

恭喜！你的 PR 已经正式送达项目维护团队，等待自动化 CI 测试与 Maintainer 的人工审查（Code Review）。

三、进阶技巧：如何保持分支与上游 (Upstream) 最新同步

在你的 PR 被审查合并前，官方仓库的 main 分支可能已经接收了其他开发者的多次合并。为了避免产生代码冲突（Merge Conflict），你需要学会同步上游。

# 1. 切换到本地 main 分支
git checkout main

# 2. 从官方上游拉取最新改动
git fetch upstream

# 3. 将上游主分支合并到本地主分支
git merge upstream/main

# 4. 同步更新你的个人远程仓库
git push origin main

# 5. 切换回你的特性分支，并将最新改动 rebase 到你的特性分支
git checkout fix/dark-mode-crash
git rebase main

# 6. 若产生冲突，手动编辑冲突文件后执行：
# git add <fixed-file>
# git rebase --continue

# 7. 强制推送到你的特性分支（由于 rebase 改变了提交历史）：
git push origin fix/dark-mode-crash --force-with-lease

小技巧：使用 --force-with-lease 代替粗暴的 -f / --force，可以在他人向同一分支推送过代码时提供安全保护，防止误覆盖他人的提交。

四、收到 Code Review 意见后如何追加改动？

很多初学者以为提了 PR 之后如果被 Maintainer 要求修改代码，需要关闭 PR 重新开一个。千万不要关闭 PR！

你只需要在本地当前特性分支继续修改：

# 继续编写代码修复审查意见中的问题
git add .
git commit -m "refactor: apply reviewer suggestions"
git push origin fix/dark-mode-crash

推送后，GitHub 上的现有 PR 会自动实时同步最新的 Commit，审查者刷新页面即可看到你的最新修改。