GitHub中开源项目维护流程手册

文章发布较早，内容可能过时，阅读注意甄别。

# 前言

混迹于互联网，或多或少难免都会与 GitHub 有交互，大多数时候在公司中积累的 git 使用经验都是面向 GitLab 的，也很容易想当然地将过往的经验套到 GitHub 中，而事实上还是有一些差别的，最近开源了几个项目，有一些还涉及到要与外部开发者协同工作，当我真正面对要处理一个 PR 的时候，内心是慌乱的，一时间不知道该从何处下手，这里就整理记录一下这方面的实践。

# 发布项目并维护

个人发布开源项目相对来说算是比较简单，通常创建仓库，然后将代码 push 上去，这些流程步骤我们都是熟悉的。

这里我不过多介绍如何创建一个项目，只说一些项目创建之后的问题。

# 基础配置

配置项目的说明，对应官网，以及标签，这些信息将辅助别人快速认识这个项目，并深入了解学习这个项目。

如果想要精简二级 tab，则可以在项目的设置中的 Features 配置项进行取舍：

在 settings 的 Pages 配置页面中，我们可以选择将该项目配置为静态站点：

# 自己维护

如果你是项目的负责人，在后期项目维护中，同样不建议直接使用本地 push 的方式进行，尽管我们有这个项目的全部权限，也可能会因为某次失手，导致将不符合预期的内容提交。这里建议走 pr 的方式进行维护，便于在 merge 的时候二次核验一下代码差异。

接下来是一个维护的常规流程。

拉取代码到本地：

$ git clone git@github.com:eryajf/learn-github.git

$ cd learn-github

$ cat README.md
# learn-github
学习GitHub相关交互以及功能

1
2
3
4
5
6
7

此时项目所在分支为默认的 main 分支，我们从最新代码切到一个测试分支。

$ git checkout -b test

# 模拟如下修改
$ echo '模拟修改提交' >> README.md

1
2
3
4

然后将 test 分支提交到远程。

$ git add .
$ git commit -m 'test'
$ git push --set-upstream origin test

1
2
3

然后我们来到 GitHub 项目页，可以看到 test 分支：

可以看到页面已经提示 test 分支，并有一个提交 PR 的按钮，我们来创建这个 PR：

通常点击 1 的 tab 进行交互，2 号可以选择当前项目的不同分支，我们这里选择刚刚的 test 分支。

编号 3 表示可以选择其他远程仓库进行合并，通常是与一个 fork 后的仓库进行交互。编号 4 可以清晰看到当前这次合并与源分支的差异。

点击创建 PR：

通常我们应该在这一步写明一个标题，以及当次将要合并的内容纲要。

此时视角切回到项目主维护者，可以通过编号 1 和编号 2 来核对提交的次数以及差异内容，这里因为是从本地推送，所以通常直接二次 check 即可，如果是处理别人的 PR，则应该将代码拉到本地进行一些功能测验。

编号 3 表示将这次 PR 进行合并，所有的提交都会合并到 main 分支中，如果该次 PR 有多次 commit，主分支也会呈现多次 commit 的历史。

编号 4 表示将多次 commit 压缩成 1 次，然后再合并到主分支，一般与协助者协同维护项目的时候，应该选择第二项。

当我们确认之后，就完成了一次自己面对项目的迭代推进流程。

# 协同流程

当我们的项目吸引了更多的同学关注之后，有一些有想法的同学可能就会参与进来，作为项目维护者，我们会面对第一个 issue，第一个 PR，这个时候不要慌，开源是一个很有包容性的理念，甚至有时候没有人关注你的某一个错漏，但你也不要因此就肆无忌惮，因为还会有人关注你的每一处用心与细节。

现在我这里用另外一个账号，模拟项目协同者，来看看这个流程会经历哪些内容。

注意接下来的内容描述将会在两个账号之间切换，这里首先将两个账号角色做个概览：

eryajf：项目 owner。
lql95：项目协作者。

通常作为协同者，我们会先把项目 fork 到自己的仓库中：

现在我处于 lql95 的视角，已经将刚刚 eryajf 名下的项目 fork 到了自己的仓库，此时可以将该项目拉到自己本地进行编码：

$ git clone git@github.com:lql95/learn-github.git

$ cd learn-github

1
2
3

将 README 内容改变如下：

$ cat README.md
# learn-github
学习GitHub相关交互以及功能
模拟修改提交

这是lql95新增的内容

- a
- b

1
2
3
4
5
6
7
8
9

编码完毕之后，就可以将代码提交到自己的远程仓库了，步骤如下：

$ git add .
$ git commit -m '以lql95的视角协同维护项目'
$ git push --set-upstream origin main

1
2
3

此时 lql95 的远程仓库实际可以相当于刚刚自己维护的 test 分支，我们需要到 eryajf 的仓库中请求对方将自己的修改 pull 过去：

方向选择正确之后，我们就可以创建这个 PR 了，同样下一步需要填写标题与备注，这里的标题备注尽量将当次 PR 的内容以列表的形式表明，以便于维护者能够直观地审核自己的这次 PR。

创建完 PR 之后，lql95 突然发现还有一些内容需要修改，于是又进行了一波编码操作：

# 调整后的内容如下
$ cat README.md
# learn-github
学习GitHub相关交互以及功能

这是lql95新增的内容

- a
- b

1
2
3
4
5
6
7
8
9

然后再次进行提交：

$ git add .
$ git commit -m '删除无用内容'
$ git push

1
2
3

这次提交同样会呈现在刚刚创建的那次 PR 之上，现在我们站在 eryajf 的视角来看看这个 PR：

可以看到 lql95 的 2 次 commit，也可以在差异页面查看此次 PR 的详情，因为这次交互内容不多，所以这里看起来比较简单，在真实项目协作过程中，一次 PR 变化的文件可能有几十个，这个时候再通过页面来看就很不直观了，可以通过如下方式在本地处理。

owner 在自己本地项目目录下，打开 .git/config 文件，在 [remote "origin"] 后添加一行：

fetch = +refs/pull/*/head:refs/pull/origin/*

然后执行 git pull 将远程内容拉到本地：

$ git pull
remote: Enumerating objects: 11, done.
remote: Counting objects: 100% (11/11), done.
remote: Compressing objects: 100% (5/5), done.
remote: Total 7 (delta 0), reused 6 (delta 0), pack-reused 0
Unpacking objects: 100% (7/7), 1.28 KiB | 435.00 KiB/s, done.
From github.com:eryajf/learn-github
   85630a4..421212d  main             -> origin/main
 * [new ref]         refs/pull/1/head -> refs/pull/origin/1
 * [new ref]         refs/pull/2/head -> refs/pull/origin/2
Your configuration specifies to merge with the ref 'refs/heads/test'
from the remote, but no such ref was fetched.

1
2
3
4
5
6
7
8
9
10
11
12

可以看到有两个 PR，我们将分支切到第二个 PR，并在本地创建一个新分支：

$ git checkout -b eryajf_test refs/pull/origin/2

此时项目在本地就将此次 PR 后的最新代码，以 eryajf_test 分支存在，我们可以对协作者提交的代码功能进行一些核验等工作，当我们测验感觉没有问题之后，就可以将代码进行合并了。合并的操作与上边一样，不再赘述。

# 其他内容

# 如何将 README 中的表格居中

这个居中指的是整个表格居中展示，而非内容的居中，查了一圈，发现将表格用如下内容包裹，就可以实现居中：

<div align="center"></div>

参考：https://stackoverflow.com/questions/24127507/is-it-possible-to-center-tables-in-a-markdown-file (opens new window)

# 协作账号问题

请务必注意协作的时候，将 git 对应的配置与 GitHub 账号的配置对齐，尤其是邮箱，否则 GitHub 找不到这个邮箱，将无法识别对应账号，你的贡献自然也无法被识别到。

这个问题解决方案参考： git 配置 github 与 gitlab 推送时指定不同用户与邮箱 (opens new window)

# 如何将多次提交合并为一次

上边讲到，我们作为协同者，可能会修改多次在同一个 PR 上，这个时候项目的 owner 可以选择压缩合并，不过作为协作者，我们应该有这种自觉，在认为代码没问题的时候，主动将多次提交合并为一次。

可以通过 rebase 进行合并，操作步骤如下，比如刚刚那次在协作者 lql95 的视角已经提交了两次，我们现在再进行一次提交：

$ echo 'test info' > test.txt
$ git add .
$ git commit 'add test file'
$ git push

1
2
3
4

这次提交之后，这个 PR 就有了三次提交，我们自己在本地做如下处理。

首先查看一下提交历史：

$ git log
commit 55e307a11369a3238d908344fea39b91d32d229f (HEAD -> main, origin/main, origin/HEAD)
Author: lql95 <eryajf@gmail.com>
Date:   Tue May 31 22:21:10 2022 +0800

    add test file

commit 0d61a99c31b2dced4fb9b1e1edfc74585571c909
Author: lql95 <eryajf@gmail.com>
Date:   Tue May 31 21:53:44 2022 +0800

    删除无用内容

commit 5c575c34b0351750510abef7ce6734b8914f951f
Author: lql95 <eryajf@gmail.com>
Date:   Tue May 31 21:44:39 2022 +0800

    以lql95的视角协同维护项目

commit 421212d25e6062dc0d15173304762056dbb3e583
Merge: 85630a4 c2cf945
Author: 二丫讲梵 <Linuxlql@163.com>
Date:   Tue May 31 21:29:58 2022 +0800

    Merge pull request #1 from eryajf/test

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

比如这里要将最新的三次提交合并，可以运行如下命令：

$ git rebase -i <421212d> # -i后面的参数为最后一个不需要合并的Commit，这里为Commit 1

执行之后，将会进入一个交互界面，内容如下：

我们把后两个 pick 改成 squash，改后如下：

这里两个关键字的含义为：

pick 表示其他的提交将会合并到这一次提交上
squash 表示将对应标识的提交合并到 pick 选择的那次 commit 上。

保存之后，进入一个新的交互页面，这个页面是填写提交信息的，可保持默认，然后保存，就合并成功了：

通过查看状态，也能看到此时的状态详情：

* dc38fb2 (HEAD -> main) 以lql95的视角协同维护项目
| * 55e307a (origin/main, origin/HEAD) add test file
| * 0d61a99 删除无用内容
| * 5c575c3 以lql95的视角协同维护项目
|/
*   421212d Merge pull request #1 from eryajf/test
|\
| * c2cf945 test
|/
* 85630a4 Create README.md