如何在 Github 上规范提交PR

GitHub 官方项目协作流程整理

0. GitHub 基础操作

从GitHub克隆

1
2
# 克隆项目到本地
git clone 项目链接
  • 在该文件夹可以通过 ls -al  查看本地库情况

将现有项目提交到 GitHub

  1. 先将所有文件添加到版本控制
1
git add .
  1. 然后在本地执行提交操作
1
git commit -m "First commit"
  1. 最后将提交的东西同步到远程版本库github上
1
git push origin master(main)
  1. 刷新GitHub能看见上传的文件

其他

  1. 将GitHub上的东西同步回本地
1
git fetch origin master(main)
  1. 查看本地或GitHub上改了什么
1
git diff origin/master
  1. 从GitHub获取最新代码并整合到本地
1
git pull origin master(main)

1. 找项目 (Finding projects)

这个很简单，确定目标项目，这里是：https://github.com/jaywcjlove/linux-command

友情提示：
做开源贡献之前，可以先看看有没有人在 issue 和 PR 中，有没有人已经提出过与你观点相同和相近的反馈意见或修改提交。注意作者是怎么回复的，避免浪费自己时间。

如果是一些小问题，而且自己时间有限，可以先提一个 issue，提醒作者本人或者其他人解决，如果没有人回应，再尝试自己提交 PR。

2. 派生一个存储库 (Forking a repository)

进入 https://github.com/jaywcjlove/linux-command项目主页，点击 Fork 按钮，创建一个新的派生项目（Create a new fork）

再点击 Create fork 按钮，创建派生项目到自己的工作区。

3. 克隆一个派生 (Cloning a fork)

进入自己的 Github 工作区，将派生项目克隆到本地（或者远端服务器）。

1
2
# 克隆项目到本地（注意是派生项目的链接，不是原始项目）
git clone 项目链接

4. 创建一个分支 (Creating a branch)

1
2
# 创建并切换到本地新分支，分支的命名尽量简洁，并与解决的问题相关
git checkout -b 新分支

5. 做出修改 (Make changes)，这个是根据自己情况修改

例如删除一行无用的代码。

6. 提交修改 (Pushing changes)

这步需要注意一下，有些项目更新的会比较频繁。当你做出修改和提交 PR 之前，可能有作者新的提交和 PR 被合并到原项目。如果有这种情况发生，在你工作区的派生项目会显示原项目有更新。例如：

点击 Update branch 之后，将原项目更新同步到派生项目。再进入本地项目文件夹

1
2
3
4
5
6
7
8
9
# 当前文件夹位置 leerob.io
# 保存本地修改并将工作目录还原到当前HEAD提交状态
git stash

# 从远程拉取最新的项目代码，将派生项目更新同步到本地
git pull origin marst

# 将保存的修改还原回当前工作目录
git stash pop

查看更新后的内容是否和本地修改有冲突，如果有就解决冲突，完成后就可以提交修改了

1
2
3
4
5
6
# 当前文件夹位置 leerob.io
# 保存本地修改并将工作目录还原到当前HEAD提交状态
git commit -am ''  

# 推到派生项目远端仓库，因为之前项目分支是在本地创建的，需要带上 '--set-upstream'
git push --set-upstream origin 分支名称

7. 创建合并请求 (Create a pull request)

回到线上派生项目的工作区，会看到新分支和修改的合并提交信息，点击 Compare & pull request

选择你想并入的原项目分支，标题和描述信息。如果有对应的 issue，就通过键入 # 添加(Github 会自动展示 issues 列表)

点击 Create pull request ，就行了。结果如下：

8. 发表评论 (Address review comments)

这部分是原项目作者需要遵循的规范。

9. 合并你的请求 (Merge your pull request)

这是原项目作者要做的，不再赘述。

10. 删除你的分支 (Delete your branch)

最后一步不是必须的，只是保持一个规范的开源协作习惯，减少意外提交错误项目分支的情况发生。

来到原项目 Github 主页，找到之前已经合并的提交请求（在关闭的 PR 列表中），点击 Delete branch

1
2
# 删除本地分支
git branch -d 分支名

注意：下次在已有的派生项目创建新分支前，要先将原项目的更新同步到派生项目，并将更新后的派生项目拉到（git pull）本地，再重新建立分支（git checkout -b new-branch-name ），再重复上述过程即可。

Github 官网对协作流程方面写很清楚，但阐述逻辑上有点混乱，而且没有中文版。有人可能会问，GitHub Docs 提供多语言访问，而且是开源的，为什么中文版有些部分没有翻译完整？详见官网对协作流程 如下：

所以，GitHub Docs 其他语言的官方翻译会滞后于英文版，因为其他语言版本不接受内容贡献（这是 Github 官方在准确度和效率之间做的一个平衡）。如果 GitHub Docs 中没有提供符合你阅读习惯的语言版本，只能发信催 Github 官方尽快提供相关语言版本。

避坑提醒： 1. 给 GitHub Docs 提交内容翻译 PR 通常是不会通过的。这里官方说的很清楚了，不接受翻译内容贡献。 2. 如果发现英文原文内容有问题（语法，语义，词法），这个是可以提交修改意见 (Issue) 和合并请求 (Pull Request) 的（其他语言的版本也都是通过英文版本翻译过来的）。但也要基于原文内容修改，自己独立创作的内容合并请求很难被 Github 官方通过。

下面是参考的相关 Github 官方文档：