龙蜥社区近期上线了​​【人人都可以参与开源】​​活动,活动里涉及了一项重要的事项就是:提!交!PR!本文就跟大家分享一下作为入门级的开发者,可以通过哪些方式参与社区建设?以及在社区参与过程当中如何提交 Pull Request(以下简称“PR”) ?本文整理自​​龙蜥大讲堂第 23 期​​


一、提交 PR 主要流程

代码库存放于 Gitee 平台上,以本次活动为例,领取的任务详情(即 Issue),以及最终提交的任务成果,都会在这个平台上进行。那么,如何在 Gitee 上提交一个 PR呢?

1、 Fork(复刻)一个代码仓库。在本次活动任务的 Issue 页上,已经写明了目标仓库。你只需要前往 Fork 目标仓库。

2、 Clone(克隆)自己的仓库到本地。

3、 建立一个分支,在分支中修改内容,然后提交 PR。

4、 编写 comments,也就是你做了哪些变更,然后等待仓库管理员的审核。

5、 如有需要,可以与管理员(一般是 SIG maintainer)进行交流,可能会需要改进自己的 PR。



6、 管理员合入你的代码后,关注自己的代码是否有改动,并积极参加评审。

如何提交一个PR?完成这 6 点就可以了_代码仓库

 

(图/提交PR流程)


二、初学者容易出错的地方

需要注意的是,初学者经常在 Git 命令上出错。常见的原因一般是:原本应该放在不同分支上修改的内容,却被放到了相同的分支上修改,相当于重叠了,这样将会与同时提交的小伙伴产生冲突。



如何提交一个PR?完成这 6 点就可以了_微信_02

 

(图/出错示例图)

上图可看出,1000 人按照不同分支同时开发没问题,那么问题经常会出在哪?就是在合并入的时候容易出错。如果想把 1000 个分支合并回来,并且不出错,在这个过程当中可能就会有一些细节问题。

怎么解决这些问题?需要初学者根据一些既定的流程来进行操作。这些既定的流程本文会写出一部分,另外一部分和公司的具体开发流程相关。



三、手把手演示如何提交PR

解决如上问题,首先就是要新建分支,接下来用具体例子来详细解释。

以 Express DPU 项目为例(是高性能的 DPU 库)。当你拿到这个项目的时候,首先想到的是这个项目我能做点什么?比如说(本文演示需要)小龙看到 Readme-cn.md 文件中有个标题是英文的,是不是可以变成中文的呢?

如何提交一个PR?完成这 6 点就可以了_代码仓库_03

接下来,就按照步骤修改这个英文标题。

 第一步:需要先 Fork 一下感兴趣的代码仓库。

点击 Fork 后选择个人。

Fork 的含义是什么?就是对代码进行修改的时候,不会影响上游的代码,这样的话防止一些误操作,并且也可以在你的代码中衍生出自己风格的代码。

如何提交一个PR?完成这 6 点就可以了_微信_04

第二步:将 Fork 好的代码仓库 Clone 到仓库本地。

Gitee 平台中会有记录,你会看到这个代码仓是“forked from”上游的代码仓。当拿到了自己的代码仓以后,就可以进行 Clone 操作,选择 HTTPS 或者是 SSH。如果选择了 SSH 的话,需要配置自己的密钥,密钥的配置在如下图所示位置。

如何提交一个PR?完成这 6 点就可以了_微信_05

接着复制 SSH,复制完了之后,要打开终端。如果没有终端,推荐用龙蜥实验室(已经预装了 Anolis OS 的免费服务器)来操作。

在终端输入 ssh-keygen -t ed25519 -C "密钥名称" ,回车三次便生成了密钥,通过查看 ~/.ssh/id_ed25519.pub 文件获取公钥。 

如何提交一个PR?完成这 6 点就可以了_微信_06

复制公钥,回到 Gitee 个人仓库的设置页面。找到【安全设置】-> 【SSH公钥】,在如下图位置粘贴公钥。

如何提交一个PR?完成这 6 点就可以了_git_07

将公钥确定保存成功后,在终端输入 ssh -T git@gitee.com ,首次添加需要键入 yes ,看到 successfully 字样,则表明添加成功。

如何提交一个PR?完成这 6 点就可以了_代码仓库_08

最后输入命令 git clone,然后粘贴 SSH 链接 ,这个第一条命令是下载代码到你的本地计算机。

 第三步:在本地建立分支、完成修改,并进行 PR 操作:

上面步骤中,下载完成后执行命令 cd ExpressUDP 进入该目录,这个时候就已经拿到了代码。Readme-cn.md 文件在这个目录下。

接下来,标准的流程是在本地建立分支、修改文件,把修改后的内容 commit 到本地仓库,再 push 回自己的代码仓,最后开一个 PR。

小贴士 1 :假设小龙直接修改,等已经修改好了后会发现这个步骤错了(其实也不能说完全是错误的),因为没有遵守标准的流程。标准流程第一步是要新建一个分支修改,不能在原来的基础上改,否则容易与其他小伙伴的代码冲突了。所以要新建一个自己的分支,在自己的分支上进行修改。对于初学者来说,往往会忽略这点,要特别注意。

如果没有创建任何分支就修改了 readme,该怎么继续操作呢?我们可以把这个修改纠正过来。先用 git status 查看状态,看到是已修改的;然后用 git checkout Readme-cn.md 还原状态,相当于把已做的修改清除了;最后再用 git status 确认下状态。

如何提交一个PR?完成这 6 点就可以了_git_09



接 下来,我们回归标准操作流程。

首先,创建一个分支:执行 git checkout-b xxx 命令创建一个分支名称。当你执行完这条命令之后,其实完成了两个操作:第一个是创建一个新的分支;第二个是切换到了创建的分支。

接着,执行 git add Readme-cn.md,就是要在分支中更新这个文件的意思。

然后,用 vim 命令修改文件中的英文标题。

如何提交一个PR?完成这 6 点就可以了_代码仓库_10

此时,可以用 git status 命令来看一下,系统提示 readme 文件已经被修改了。用 git log 可以查看代码仓库的修改历史。

如何提交一个PR?完成这 6 点就可以了_微信_11



接下来,执行 git commit -vs,输入修改说明。命令中的 vs 是为了加上签名并显示修改内容。

此时小龙修改的内容还在本地,要是想把它放到服务器上,就要经过 push。直接执行 git push 的时候就会告诉你要用 git push --set-upstream origin <分支名> 这条命令来关联远程分支,关联后,接下来 push 可以直接用 git push origin 了。

小贴士 2 :这个时候有两个 remote,这两个 remote 表达的是什么?是个人仓库和原始仓库。小龙为什么要这么做?大家可以想象 upstream 上的代码变化是非常频繁的。但是这个仓库是从 upstream fork 过来的。那么当 upstream 在变化的时候,仓库理论上是不会变化了。但是怎么样能拿到 upstream 最新的代码?重新克隆一遍都没有问题。但如果小龙设置了两个 remote ,其实操作就很简单,指定从 upstream 上拉代码,就可以快速的跟进过来(这是作者的一个使用习惯)。

如何提交一个PR?完成这 6 点就可以了_微信_12

参考下面的命令来完成 push 。

如何提交一个PR?完成这 6 点就可以了_微信_13

从上图可以看到,push 后系统会有一句提示(这个提示其实是 Git 仓库给过来的),并提供了一个“

​https://gitee.com​

”开头的链接,你可以直接通过该链接在网站上创建一个 PR。

打开这个链接,注意“源分支”保留默认值,但“目标分支”需要修改,在这个示例中目标应该指向 anolis 的 master。

第四步:编写 comments 并等待 review。

comments(也就是 commit log)已经在上一步中输入过了。此步骤的重要性不亚于写代码,因为comments只有清晰明了地记录你的改动,例如修改点、是否校验、评估的影响等,才能让审核人快速看懂。

第五步:提交了 PR 以后,就会分配给审核人,等待审查和测试。通过后才能合入代码库。这期间,建议与 Maintainer 多进行互动。

第六步:合入后关注自己的代码是否有改动,并积极参加评审。

如何提交一个PR?完成这 6 点就可以了_代码仓库_14

根据全文,最后总结下要想提交一个 PR,需要以下 6 个步骤:

1、需要先 Fork 一下感兴趣的代码仓库;

2、将 Fork 好的代码仓库 Clone 到仓库本地;

3、然后在本地建立分支、修改完成,并进行PR操作;

4、编写 comments 并等待 review,此步骤的重要性不亚于写代码;

5、与 maintainer 进行交互,反馈建议改进自己的 PR,这个过程可能耗时较久;

6、合入后关注自己的代码是否有改动,并积极参加评审。 

—— 完 ——