【转载】开源PR教程---我要提交 PR，怎么上手？

最近在参与开源项目，对于pr流程还不太清晰，看到了一篇不错的介绍文章，这篇文章摘取重要的部分转载一下。文章末尾有标注原文。

我要提交 PR，怎么上手？

一般开源项目代码库根目录都会有一个 CONTRIBUTING.md 或者其他类似名字的文档来介绍如何开始贡献，像这样：

DevStream Contributing

在 DevStream 的 Contributing 文档里我们放了一个 Development Workflow，其实就是 PR 工作流的介绍，不过今天，我要更详细地聊聊 PR 工作流。

5.1、第一步：Fork 项目仓库

GitHub 上的项目都有一个 Fork 按钮，我们需要先将开源项目 fork 到自己的账号下，以 DevStream 为例：

Fork DevStream

点一下 Fork 按钮，然后回到自己账号下，可以找到 fork 到的项目了：

DevStream Fork

这个项目在你自己的账号下，也就意味着你有任意修改的权限了。我们后面要做的事情，就是将代码变更提到自己 fork 出来的代码库里，然后再通过 Pull Request 的方式将 commits 合入上游项目。

5.2、第二步：克隆项目仓库到本地

对于任意一个开源项目，流程几乎都是一样的。我直接写了一些命令，大家可以复制粘贴直接执行。当然，命令里的一些变量还是需要根据你自己的实际需求修改，比如对于 DevStream 项目，我们可以先这样配置几个环境变量：

环境变量

export WORKING_PATH="~/gocode"
export USER="daniel-hutao"
export PROJECT="devstream"
export ORG="devstream-io"

同理对于 DevLake，这里的命令就变成了这样：

export WORKING_PATH="~/gocode"
export USER="daniel-hutao"
export PROJECT="incubator-devlake"
export ORG="apache"

记得 USER 改成你的 GitHub 用户名，WORKING_PATH 当然也可以灵活配置，你想把代码放到哪里，就写对应路径。

接着就是几行通用的命令来完成 clone 等操作了：

clone 等

mkdir -p ${WORKING_PATH}
cd ${WORKING_PATH}
# You can also use the url: [email protected]:${USER}/${PROJECT}.git
# if your ssh configuration is proper
git clone https://github.com/${USER}/${PROJECT}.git
cd ${PROJECT}

git remote add upstream https://github.com/${ORG}/${PROJECT}.git
# Never push to upstream locally
git remote set-url --push upstream no_push

如果你配置好了 ssh 方式来 clone 代码，当然，git clone 命令用的 url 可以改成[email protected]:${USER}/${PROJECT}.git。

完成这一步后，我们在本地看到的 remote 信息应该是这样的：

git remote -v

origin	[email protected]:daniel-hutao/devstream.git (fetch)
origin	[email protected]:daniel-hutao/devstream.git (push)
upstream	https://github.com/devstream-io/devstream (fetch)
upstream	no_push (push)

记住啰，你本地的代码变更永远只提交到 origin，然后通过 origin 提交 Pull Request 到 upstream。

5.3、第三步：更新本地分支代码

如果你刚刚完成 fork 和 clone 操作，那么你本地的代码肯定是新的。但是“刚刚”只存在一次，接着每一次准备开始写代码之前，你都需要确认本地分支的代码是新的，因为基于老代码开发你会陷入无限的冲突困境之中。

更新本地 main 分支代码：

git fetch upstream
git checkout main
git rebase upstream/main

当然，我不建议你直接在 main 分支写代码，虽然你的第一个 PR 从 main 提交完全没有问题，但是如果你需要同时提交2个 PR 呢？总之鼓励新增一个 feat-xxx 或者 fix-xxx 等更可读的分支来完成开发工作。

创建分支

git checkout -b feat-xxx

这样，我们就得到了一个和上游 main 分支代码一样的特性分支 feat-xxx 了，接着可以开始愉快地写代码啦！

5.4、第四步：写代码

没啥好说的，写就是了，写！

5.5、第五步：Commit 和 Push

通用的流程：

git add <file>
git commit -s -m "some description here"
git push origin feat-xxx

当然，这里大家需要理解这几个命令和参数的含义，灵活调整。比如你也可以用git add --all完成 add 步骤，在 push 的时候也可以加-f参数，用来强制覆盖远程分支（假如已经存在，但是 commits 记录不合你意）。但是请记得git commit的-s参数一定要加哦！

如果你习惯用 IDE 来 commit，当然也没有任何问题，像这样：

DevStream Commit with Goland

这里要注意 commit message 的规范，可能每个开源项目的要求不尽相同，比如 DevStream 的规范是类似这样的格式：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

举几个例子：

feat: some description here
docs: some description here
fix: some description here
fix(core): some description here
chore: some description here
…

commit 和 push 两个步骤可以在 IDE 里一步到位，也可以分开，我习惯分开操作，给自己多一些余地。另外，我更习惯命令行操作：

git push origin feat-1

Counting objects: 80, done.
Delta compression using up to 10 threads.
Compressing objects: 100% (74/74), done.
Writing objects: 100% (80/80), 13.78 KiB | 4.59 MiB/s, done.
Total 80 (delta 55), reused 0 (delta 0)
remote: Resolving deltas: 100% (55/55), completed with 31 local objects.
remote: 
remote: Create a pull request for 'feat-1' on GitHub by visiting:
remote:      https://github.com/daniel-hutao/devstream/pull/new/feat-1
remote: 
To github.com:daniel-hutao/devstream.git
 * [new branch]      feat-1 -> feat-1

到这里，本地 commits 就推送到远程了。

5.6、第六步：开一个 PR

在完成 push 操作后，我们打开 GitHub，可以看到一个黄色的提示框，告诉我们可以开一个 Pull Request 了：

Compare & pull request

如果你没有看到这个框，也可以直接切换到 feat-1 分支，然后点击下方的“Contribute”按钮来开启一个 PR，或者直接点 Issues 边上的 Pull requests 进入对应页面。

Pull Request 格式默认是这样的：

DevStream Pull Request

这里我们需要填写一个合适的标题（默认和 commit message 一样），然后按照模板填写 PR 描述。PR 模板其实在每个开源项目里都不太一样，我们需要仔细阅读上面的内容，避免犯低级错误。

比如 DevStream 的模板里目前分为4个部分：

Pre-Checklist：这里列了3个前置检查项，提醒 PR 提交者要先阅读 Contributing 文档，然后代码要有完善的注释或者文档，尽可能添加测试用例等；
Description：这里填写的是 PR 的描述信息，也就是介绍你的 PR 内容的，你可以在这里描述这个 PR 解决了什么问题等；
Related Issues：记得吗？我们在开始写代码之前其实是需要认领 issue 的，这里要填写的也就是对应 issue 的 id，假如你领的 issue 链接是 :bomb: `Bug`: quickstart.sh wrongly determinates cpu architecture · Issue #796 · devstream-io/devstream · GitHub，并且这个 issue 通过你这个 PR 的修改后就完成了，可以关闭了，这时候可以在 Related Issues 下面写“close #796”；
New Behavior：代码修改后绝大多数情况下是需要进行测试的，这时候我们可以在这里粘贴测试结果截图，这样 reviewers 就能够知道你的代码已经通过测试，功能符合预期，这样可以减少 review 工作量，快速合入。

这个模板并不复杂，我们直接对着填写就行。

比如：

DevStream Pull Request Template

然后点击右下角“Create pull request”就完成了一个 PR 的创建了。不过我这里不能去点这个按钮，我用来演示的修改内容没有意义，不能合入上游代码库。不过我还是想给你看下 PR 创建出来后的效果，我们以 pr655 为例吧：

DevStream Pull Request 655

这是上个月我提的一个 PR，基本和模板格式一致。除了模板的内容，可能你已经注意到这里多了一个 Test 小节，没错，模板不是死的，模板只是为了降低沟通成本，你完全可以适当调整，只要结果是“往更清晰的方向走”的。我这里通过 Test 部分添加了本地详细测试结果记录，告诉 reviewers 我已经在本地充分测试了，请放心合入。

提交了 PR 之后，我们就可以在 PR 列表里找到自己的 PR 了，这时候还需要注意 ci 检查是不是全部能够通过，假如失败了，需要及时修复。以 DevStream 为例，ci 检查项大致如下：

DevStream CI Checks

5.7、第七步：PR 合入

如果你的 PR 很完美，毫无争议，那么过不了太长时间，项目管理员会直接合入你的 PR，那么你这个 PR 的生命周期也就到此结束了。

但是，没错，这里有个“但是”，但是往往第一次 PR 不会那么顺利，我们接下来就详细介绍一下可能经常遇到的一些问题和对应的解决办法。

六、我提交了一个 PR，然后遇到了问题 A,B,C,D,E,F,G,…😭

多数情况下，提交一个 PR 后是不会被马上合入的，reviewers 可能会提出各种修改意见，或者我们的 PR 本身存在一些规范性问题，或者 ci 检查就直接报错了，怎么解决呢？继续往下看吧。

6.1、Reviewers 提了一些修改意见，我如何更新 PR？

很多时候，我们提交了一个 PR 后，还需要继续追加 commit，比如提交后发现代码还有点问题，想再改改，或者 reviewers 提了一些修改意见，我们需要更新代码。

一般我们遵守一个约定：在 review 开始之前，更新代码尽量不引入新的 commits 记录，也就是能合并就合并，保证 commits 记录清晰且有意义；在 review 开始之后，针对 reviewers 的修改意见所产生的新 commit，可以不向前合并，这样能够让二次 review 工作更有针对性。

不过不同社区要求不一样，可能有的开源项目会要求一个 PR 里只能包含一个 commit，大家根据实际场景灵活判断即可。

说回如何更新 PR，我们只需要在本地继续修改代码，然后通过和第一个 commit 一样的步骤，执行这几个命令：

git add <file>
git commit -s -m "some description here"
git push origin feat-xxx

这时候别看 push 的是 origin 的 feat-xxx 分支，其实 GitHub 会帮你把新增的 commits 全部追加到一个未合入 PR 里去。没错，你只管不断 push，PR 会自动更新。

至于如何合并 commits，我们下一小节具体介绍。

6.2、Commits 太多或者记录混乱，如何合并 Commits？

很多情况下我们需要去合并 commits，比如你的第一个 commit 里改了100行代码，然后发现少改了1行，这时候又提交了一个 commit，那么第二个 commit 就太“没意思”了，我们需要合并一下。

6.2.1、Git 命令行方式合并 Commits

比如我这里有2个同名的 commits，第二个 commit 其实只改了一个标点：

Commits to be Merged

这时候我们可以通过 rebase 命令来完成2个 commits 的合并：

git rebase -i HEAD~2

执行这个命令会进入一个编辑页面，默认是 vim 编辑模式，内容大致如下：

pick 3114c0f docs: just for test
pick 9b7d63b docs: just for test

# Rebase d640931..9b7d63b onto d640931 (2 commands)
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.

我们需要把第二个 pick 改成 s，然后保存退出(vim 的 wq 命令)：

pick 3114c0f docs: just for test
s 9b7d63b docs: just for test

接着会进入第二个编辑页面：

# This is a combination of 2 commits.
# This is the 1st commit message:

docs: just for test

Signed-off-by: Daniel Hu <[email protected]>

# This is the commit message #2:

docs: just for test

Signed-off-by: Daniel Hu <[email protected]>

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# ...

这里是用来编辑合并后的 commit message 的，我们直接删掉多余部分，只保留这样几行：

docs: just for test

Signed-off-by: Daniel Hu <[email protected]>

接着同样是 vim 的保存退出操作，这时候可以看到日志：

[detached HEAD 80f5e57] docs: just for test
 Date: Wed Jul 6 10:28:37 2022 +0800
 1 file changed, 2 insertions(+)
Successfully rebased and updated refs/heads/feat-1.

这时候可以通过git log命令查看下 commits 记录是不是符合预期：

Rebased

好，我们在本地确认 commits 已经完成合并，这时候就可以继续推送到远程，让 PR 也更新掉：

git push -f origin feat-xxx

这里需要有一个-f参数来强制更新，合并了 commits 本质也是一种冲突，需要冲掉远程旧的 commits 记录。

6.2.2 IDE 里合并 Commits

图形化方式当然也可以实现 Commits 的合并。

截图走起

Squash with Goland

点击右下角的 Git
选择想要合并的 commits
右键，然后点击 Squash Commits，记得嘴里默念一句：走你！

接着就可以看到这个页面了：

Squash with Goland

这是图形化方式修改 commit message 的页面，行吧，改成你喜欢的样子，然后点击右下角的 OK 按钮，事情就算结束了。

Squash with Goland

看，2个 commits，它们“融合”了，变成了一个“改头换面”的新 commit 了。

6.3、PR 产生了冲突，如何解决？

冲突可以在线解决，也可能本地解决，我们逐个来看。

6.3.1、在线解决冲突

我们要尽可能避免冲突，养成每次写代码前更新本地代码的习惯。不过，冲突不可能完全避免，有时候你的 PR 被阻塞了几天，可能别人改了同一行代码，还抢先被合入了，这时候你的 PR 就出现冲突了，类似这样（同样，此刻我不能真的去上游项目构造冲突，所以下面用于演示的冲突在我在自己的 repo 里）：

Conflict Happened

每次看到这个页面都会让人觉得心头一紧。我们点击“Resolve conflicts”按钮，就可以看到具体冲突的内容了：

Conflict File

可以看到具体冲突的行了，接下来要做的就是解决冲突。我们需要删掉所有的 <<<<<<<、>>>>>>> 和 ======= 标记，只保留最终想要的内容，如下：

Conflict Resolved

接着点击右上角的“Mark as Resolved”：

Mark as resolved

最后点击“Commit merge”：

Commit Merge

这样就完成冲突解决了，可以看到产生了一个新的 commit：

Conflict Resolved

到这里，冲突就解决掉了。

6.3.2、本地解决冲突

更多时候，我们需要在本地解决冲突，尤其是冲突太多，太复杂的时候。

同样，我们构造一个冲突，这次尝试在本地解决冲突。

先在线看一下冲突的内容：

Conflict Happened

接着我们在本地执行：

# 先切回到 main 分支
git checkout main
# 拉取上游代码（实际场景肯定是和上游冲突，我们这里的演示环境其实是 origin）
git fetch upstream
# 更新本地 main（这里也可以用 rebase，但是 reset 不管有没有冲突总是会成功）
git reset --hard upstream/main

到这里，本地 main 分支就和远程(或者上游) main 分支代码完全一致了，然后我们要做的是将 main 分支的代码合入自己的特性分支，同时解决冲突。

git checkout feat-1
git rebase main

这时候会看到这样的日志：

First, rewinding head to replay your work on top of it...
Applying: docs: conflict test 1
Using index info to reconstruct a base tree...
M       README.md
Falling back to patching base and 3-way merge...
Auto-merging README.md
CONFLICT (content): Merge conflict in README.md
error: Failed to merge in the changes.
Patch failed at 0001 docs: conflict test 1
The copy of the patch that failed is found in: .git/rebase-apply/patch

Resolve all conflicts manually, mark them as resolved with
"git add/rm <conflicted_files>", then run "git rebase --continue".
You can instead skip this commit: run "git rebase --skip".
To abort and get back to the state before "git rebase", run "git rebase --abort".

我们需要解决冲突，直接打开 README.md，找到冲突的地方，直接修改。这里的改法和上一小节介绍的在线解决冲突没有任何区别，我就不赘述了。

代码里同样只保留最终内容，然后继续 git 命令走起来：

Conflict Resolved

可能此时你并不放心，那就通过git log命令看一下 commits 历史记录吧：

Commits History

这里的“conflict test 2”是我提交到 main 分支的记录，可以看到这个时间比“conflict test 1”还要晚了一些，但是它先合入了。我们在 rebase 操作后，这个记录在前，我们特性分支的“conflict test 1”在后，看起来很和谐，我们继续将这个变更推送到远程，这个命令已经出现很多次了：

git push -f origin feat-xxx

这时候我们再回到 GitHub 看 PR 的话，可以发现冲突已经解决了，并且没有产生多余的 commit 记录，也就是说这个 PR 的 commit 记录非常干净，好似冲突从来没有出现过：

Clear Commits Record

至于什么时候可以在线解决冲突，什么时候适合本地解决冲突，就看大家如何看待“需不需要保留解决冲突的记录”了，不同社区的理解不一样，可能特别成熟的开源社区会希望使用本地解决冲突方式，因为在线解决冲突产生的这条 merge 记录其实“没营养”。至于 DevStream 社区和 DevLake 社区，我们推荐使用后一种，但是不做强制要求。

6.4、CI 检查不过：commit message 相关问题如何修复？

前面我们提到过 commit message 的规范，但是第一次提交 PR 的时候还是很容易出错，比如feat: xxx其实能通过 ci 检查，但是feat: Xxx就不行了。假设现在我们不小心提交了一个 PR，但是里面 commit 的 message 不规范，这时候怎么修改呢？

太简单了，直接执行：

git commit --amend

这条命令执行后就能进入编辑页面，随意更新 commit message 了。改完之后，继续 push：

git push -f origin feat-xxx

这样就能更新 PR 里的 commit message 了。

6.5、CI 检查不过：DCO(sign) 问题如何修复？

相当多的开源项目会要求所有合入的 commits 都包含一行类似这样的记录：

Daniel Hu <[email protected]>

所以 commit message 看起来会像这样：

feat: some description here
    
Signed-off-by: Daniel Hu <[email protected]>

这行信息相当于是对应 commit 的作者签名。要添加这样一行签名当然很简单，我们直接在git commit命令后面加一个-s参数就可以了，比如git commit -s -m "some description here"提交的 commit 就会带上你的签名。

但是如果如果你第一次提交的 PR 里忘记了在 commits 中添加 Signed-off-by 呢？这时候，如果对应开源项目配置了 DCO 检查，那么你的 PR 就会在 ci 检查中被“揪出来”没有正确签名。

同样先构造一个没有加签名的 commit：

Commit Without Sign

我不能直接推到 DevStream 项目代码库里演示如何让 DCO 报错，但是如果提 PR，看到的效果是这样的：

Commit With DCO Error

我们看下如何解决：

git commit --amend -s

这样一个简单的命令，就能直接在最近一个 commit 里加上 Signed-off-by 信息。执行这行命令后会直接进入 commit message 编辑页面，默认如下图：

docs: dco test

Signed-off-by: Daniel Hu <[email protected]>

这时候我们可以同时修改 commit message，如果不需要，那就直接保存退出好了，签名信息是会自动加上的。

完成签名后呢？当然是来一个强制 push 了：

git push -f origin feat-xxx

这样，你 PR 中的 DCO 报错就自然修复了。

如何参与开源项目 - 细说 GitHub 上的 PR 全过程 - DevStream Bloghttps://blog.devstream.io/posts/open-a-pr-in-github/