Github 开源项目提交PR（Pull Request）流程指南

本指南将帮助你了解如何向开源项目提交 Pull Request。

准备工作
[Fork 和克隆仓库](#Fork 和克隆仓库 "#fork-%E5%92%8C%E5%85%8B%E9%9A%86%E4%BB%93%E5%BA%93")
[配置 Git 用户信息](#配置 Git 用户信息 "#%E9%85%8D%E7%BD%AE-git-%E7%94%A8%E6%88%B7%E4%BF%A1%E6%81%AF")
创建功能分支
进行代码修改
提交代码
[推送到你的 Fork](#推送到你的 Fork "#%E6%8E%A8%E9%80%81%E5%88%B0%E4%BD%A0%E7%9A%84-fork")
[创建 Pull Request](#创建 Pull Request "#%E5%88%9B%E5%BB%BA-pull-request")
[更新 Pull Request](#更新 Pull Request "#%E6%9B%B4%E6%96%B0-pull-request")
常见问题

准备工作

1. 创建 GitHub 账号

如果你还没有 GitHub 账号，请先注册：github.com/join

2. 创建 Personal Access Token

GitHub 从 2021 年 8 月开始不再支持使用密码进行 HTTPS 认证，必须使用 Personal Access Token。

创建步骤：

访问：github.com/settings/to...
点击 "Generate new token" → "Generate new token (classic)"
填写 Token 描述（例如：xxx PR）
选择过期时间
重要：勾选 repo 权限（完整仓库权限）
点击 "Generate token"
立即复制并保存 token（只显示一次！）

⚠️ 安全提示：Token 相当于你的密码，请妥善保管，不要分享给他人。

Fork 和克隆仓库

1. Fork 仓库

访问项目仓库：github.com/xxx/xxx
点击右上角的 "Fork" 按钮
选择你的账号进行 Fork
Fork 完成后，你的仓库地址将是：https://github.com/YOUR_USERNAME/xxx.git

2. 克隆你的 Fork

bash 复制代码

# 克隆你的 Fork（将 YOUR_USERNAME 替换为你的 GitHub 用户名，xxx 替换为项目名称）
git clone https://github.com/YOUR_USERNAME/xxx.git
cd xxx

3. 添加上游仓库

bash 复制代码

# 添加上游仓库（原始仓库，将 xxx/xxx 替换为原始仓库的组织名/项目名）
git remote add upstream https://github.com/xxx/xxx.git

# 验证 remote 配置
git remote -v

你应该看到：

origin：指向你的 Fork
upstream：指向原始仓库

配置 Git 用户信息

⚠️ 重要：为仓库单独配置用户信息

为了避免提交关联到错误的用户，强烈建议为每个仓库单独配置用户信息。

方法一：为当前仓库配置（推荐）

bash 复制代码

# 设置当前仓库的用户名和邮箱（不影响全局配置）
git config --local user.name "你的GitHub用户名"
git config --local user.email "你的GitHub邮箱"

# 验证配置
git config --local user.name
git config --local user.email

方法二：使用全局配置

bash 复制代码

# 设置全局用户名和邮箱（影响所有仓库）
git config --global user.name "你的GitHub用户名"
git config --global user.email "你的GitHub邮箱"

配置 HTTPS 认证

bash 复制代码

# 配置 credential helper（macOS）
git config --local credential.helper osxkeychain

# 或者配置为使用你的用户名（推送时只需输入 token，将 xxx 替换为项目名称）
git remote set-url origin https://YOUR_USERNAME@github.com/YOUR_USERNAME/xxx.git

创建功能分支

1. 同步上游代码

bash 复制代码

# 切换到 main 分支
git checkout main

# 拉取上游最新代码
git fetch upstream

# 合并上游 main 分支
git merge upstream/main

2. 创建新分支

根据你的修改类型创建分支：

bash 复制代码

# 功能开发
git checkout -b feature/your-feature-name

# Bug 修复
git checkout -b bugfix/your-bugfix-name

# 文档更新
git checkout -b docs/your-docs-update

分支命名规范：

feature/：新功能
bugfix/：Bug 修复
docs/：文档更新
refactor/：代码重构
test/：测试相关

进行代码修改

在 IDE 中打开项目
进行代码修改
确保代码符合项目规范（参考 CONTRIBUTING.md）

提交代码

1. 查看修改

bash 复制代码

# 查看修改的文件
git status

# 查看具体的修改内容
git diff

2. 添加修改

bash 复制代码

# 添加所有修改
git add .

# 或者添加特定文件
git add path/to/your/file.xxx

3. 提交修改

遵循 Angular Commit Convention：

bash 复制代码

# 提交格式：<type>: <subject>
git commit -m "fix: 修复的问题描述"

提交类型：

feat：新功能
fix：Bug 修复
docs：文档变更
style：代码格式（不影响代码运行）
refactor：重构（既不是新功能也不是 Bug 修复）
test：添加测试
chore：构建过程或辅助工具的变动

4. 验证提交信息

bash 复制代码

# 查看提交历史
git log --oneline -5

# 查看提交的详细信息（包括作者）
git log --format="%h %an <%ae> - %s" -1

确保提交显示正确的作者信息！

推送到你的 Fork

1. 首次推送

bash 复制代码

# 推送并设置上游分支
git push --set-upstream origin your-branch-name

2. 后续推送

bash 复制代码

# 直接推送
git push origin your-branch-name

3. 输入凭证

推送时会提示输入凭证：

Username：你的 GitHub 用户名
Password ：输入你的 Personal Access Token（不是 GitHub 密码）

首次输入后，macOS 的 Keychain 会保存凭证，后续不需要重复输入。

创建 Pull Request

方法一：使用 GitHub 提供的链接（推荐）

推送成功后，GitHub 会在终端显示创建 PR 的链接，直接访问即可。

方法二：手动创建

访问你的 Fork：https://github.com/YOUR_USERNAME/xxx（将 xxx 替换为项目名称）
你会看到提示 "Compare & pull request"，点击它
或者访问原始仓库：github.com/xxx/xxx（将 xxx/xxx 替换为原始仓库的组织名/项目名）
点击 "Pull requests" 标签
点击 "New pull request"
点击 "compare across forks"
选择：
- base repository : xxx/xxx → main（将 xxx/xxx 替换为原始仓库）
- head repository : YOUR_USERNAME/xxx → your-branch-name（将 xxx 替换为项目名称）
填写 PR 信息：
- Title：清晰的标题，描述你的修改
- Description：详细描述你的修改内容、原因、测试情况等
点击 "Create pull request"

PR 描述模板

markdown 复制代码

## 修改类型
- [ ] Bug 修复
- [ ] 新功能
- [ ] 文档更新
- [ ] 代码重构
- [ ] 其他

## 修改描述
简要描述你的修改内容

## 修改原因
为什么需要这个修改

## 测试情况
- [ ] 已测试
- [ ] 测试通过
- [ ] 需要测试

## 相关 Issue
关联的 Issue 编号（如果有）

## 截图（如适用）

更新 Pull Request

方式一：添加新提交（推荐）

适用于需要添加新的修改：

bash 复制代码

# 1. 修改代码后
git add .
git commit -m "你的提交信息"
git push origin your-branch-name

新提交会自动出现在 PR 中。

方式二：修改最新提交

适用于修改最后一次提交：

bash 复制代码

# 1. 修改代码后
git add .
git commit --amend --no-edit  # 或者 --amend -m "新的提交信息"
git push --force-with-lease origin your-branch-name

⚠️ 注意：使用 --force-with-lease 而不是 --force，更安全。

方式三：修改历史提交

适用于修改多个提交或非最新提交：

bash 复制代码

# 1. 交互式 rebase（例如修改最近3个提交）
git rebase -i HEAD~3

# 2. 在编辑器中，将要修改的提交前的 'pick' 改为 'edit'
# 3. 保存退出后，修改代码
git add .
git commit --amend --no-edit
git rebase --continue

# 4. 强制推送
git push --force-with-lease origin your-branch-name

常见问题

1. 为什么我的提交关联到了错误的用户？

问题原因：

提交时使用了错误的 Git 用户配置（全局配置或其他仓库的配置）

解决方案：

方法一：修改最新提交的作者

bash 复制代码

# 修改最后一次提交的作者
git commit --amend --author="你的用户名 <你的邮箱>" --no-edit

# 强制推送
git push --force-with-lease origin your-branch-name

方法二：修改历史提交的作者

bash 复制代码

# 使用 git rebase 修改历史提交
git rebase -i HEAD~N  # N 是要修改的提交数量

# 在编辑器中将要修改的提交前的 'pick' 改为 'edit'
# 保存退出后，对每个提交执行：
git commit --amend --author="你的用户名 <你的邮箱>" --no-edit
git rebase --continue

# 强制推送
git push --force-with-lease origin your-branch-name

预防措施：

为每个仓库单独配置用户信息：

bash 复制代码

git config --local user.name "你的GitHub用户名"
git config --local user.email "你的GitHub邮箱"

2. 推送时提示 "Permission denied"

可能原因：

使用了 GitHub 密码而不是 Personal Access Token
Token 权限不足
账号没有仓库的写权限

解决方案：

确保使用 Personal Access Token 而不是密码
检查 Token 是否包含 repo 权限
如果 Fork 了仓库，确保推送到你的 Fork 而不是原始仓库

3. 如何同步上游代码？

bash 复制代码

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

# 2. 拉取上游最新代码
git fetch upstream

# 3. 合并上游 main 分支
git merge upstream/main

# 4. 推送到你的 Fork
git push origin main

# 5. 切换回你的功能分支
git checkout your-branch-name

# 6. 将 main 的更新合并到你的分支
git merge main

4. PR 被关闭或需要重新打开

如果 PR 被关闭，你可以：

修复问题后，推送新的提交
在 PR 页面点击 "Reopen pull request"

5. 如何撤销本地提交？

bash 复制代码

# 撤销最后一次提交（保留修改）
git reset --soft HEAD~1

# 撤销最后一次提交（不保留修改）
git reset --hard HEAD~1

# 撤销多个提交
git reset --hard HEAD~N  # N 是要撤销的提交数量

最佳实践

保持分支更新：定期同步上游代码到你的分支
提交信息清晰：使用规范的提交信息格式
小步提交：将大的修改拆分成多个小的、有意义的提交
测试代码：提交前确保代码可以正常编译和运行
遵循规范：遵守项目的代码规范和提交规范
详细描述：PR 描述要清晰，帮助维护者理解你的修改
及时响应：关注 PR 的评论，及时回复和修改

获取帮助

如果遇到问题，可以通过以下方式获取帮助：

查看 CONTRIBUTING.md
在 GitHub Issues 中提问
查看项目的文档

总结

完整的 PR 流程：

bash 复制代码

# 1. Fork 仓库（在 GitHub 网页上操作）

# 2. 克隆你的 Fork（将 YOUR_USERNAME 和 xxx 替换为实际值）
git clone https://github.com/YOUR_USERNAME/xxx.git
cd xxx

# 3. 添加上游仓库（将 xxx/xxx 替换为原始仓库的组织名/项目名）
git remote add upstream https://github.com/xxx/xxx.git

# 4. 配置用户信息
git config --local user.name "你的GitHub用户名"
git config --local user.email "你的GitHub邮箱"

# 5. 同步上游代码
git checkout main
git fetch upstream
git merge upstream/main

# 6. 创建功能分支
git checkout -b feature/your-feature-name

# 7. 修改代码...

# 8. 提交代码
git add .
git commit -m "feat: 你的功能描述"

# 9. 推送到你的 Fork
git push --set-upstream origin feature/your-feature-name

# 10. 在 GitHub 上创建 PR

祝你贡献愉快！🎉

Github 开源项目提交PR（Pull Request）流程指南