参与github上开源项目的大致流程和注意事项（重要）

2020-12-14 02:16:32 编辑 0 阅读量:855

GitHub的官方帮助如下：

Fork A Repo: https://help.github.com/articles/fork-a-repo
    Using Pull Requests: https://help.github.com/articles/using-pull-requests
    Merging a pull request: https://help.github.com/articles/merging-a-pull-request
    Closing a pull request: https://help.github.com/articles/closing-a-pull-request
    Tidying up Pull Requests: https://help.github.com/articles/tidying-up-pull-requests

发现这个官方文档写得比较简单，并没有提到开源项目协作方式的一些必要的trick（比如建立topic branch），还有PullRequest的运作细节也没有提到。写个简单的总结补充一下。
一：Fork原项目
        fork就相当于把别人的项目克隆到自己的账号下一份，以后你的修改都应是提交到你自己github账号下的这个项目中，你是没有权限直接push到原作者账号下的项目中的

二:clone项目到本地
　    1、复制项目clone地址
            注意是clone自己账号下的项目地址，不是原作者的，原作者的你虽然也可以clone到本地，但是你是没push权限的。还要注意这里咱们使用ssh协议，所以要选择ssh类型的地址
        2、clone 到本地，
            在命令行下 输入 git clone 并将复制的地址添加上，然后执行git clone ***
三、将项目原地址添加为远程仓库

复制原作者的项目地址，添加为自己的一个远程仓库，用来实时将原项目的修改更新到咱们本地并合并。注意也是复制ssh协议类型的地址，然后

```
# upstream就代指官方库
git remote add upstream 网址
```

使用 git remote -v可以看到我们有两个仓库一个origin，咱们自己的github仓库；一个upstream，原作者的远程仓库。当然也可以不用upstream这个名字。

三： 创建你的branch

这一步非常重要。GitHub的帮助里没有提到创建主题branch的必要性，你当然可以直接在原项目的默认branch（如master）上进行工作，但实际上：

如果打算为原项目作贡献，强烈建议你为每个主题创建一个单独的branch。

举例：如果需要修复原项目的一个和Unicode相关的issue：

```
$ git branch fix-unicode-error
$ git checkout fix-unicode-error
```

然后在自己的主题branch（这里是fix-unicode-error）下进行工作。

四: 在主题branch下完成需要的工作

记得push相应的主题branch到GitHub。
*（针对贡献者）rebase还是merge？

从实用的角度来讲，

当你在主题branch下工作，想要导入来自上游库的（与你当前的工作不冲突的情况下）更新时，使用git rebase。

例如，（假设上游branch为upstream/master）

$ git rebase upstream/master fix-unicode-error

或者直接（如果当前branch已经是fix-unicode-error）：

$ git rebase upstream/master

这将把当前branch的开发“base（基础）”推进到一个新的起点，而不会引入多余的commits。

当你在某个branch下工作时，git merge可以用来合并来自其他branch的更新。

如果merge的branch来自远程库，一次merge操作会增加一个额外的commit（“Merge branch 'master' of something”）。如果在一个需要发送Pull Request的主题branch下面进行这种操作，（我个人觉得）这不是一种干净的手段。

当你在主线branch（例如master）下进行开发时，git merge可以用来吸收其他开发branch引入的新特性（包括主项目维护者用来直接merge Pull Requests），很恰当。

五: 发送第一个Pull Request

GitHub的界面：左边选择base branch，右边选择head branch。

base branch：相当于target branch，你希望Pull Request被merge到上游项目的哪个branch里。
        为什么要叫base branch：base可以理解为你在进行git rebase操作时的那个“base”，也就是你的主题branch所基于的开发base（基础）。

head branch：相当于source branch，你希望自己开发库里的哪个branch被用来进行Pull Request（当然也就是你的主题branch）。
        为什么要叫head branch：参见下面关于head的定义。

注意head与HEAD（大写）的区别：

head：简单地理解，就是指向某个commit对象的一个reference。它可以是一个branch的名称（例如，默认的master），也可以是一个tag的名称。一个库可以同时有任意多个head。

HEAD：当前活动的head。在任意时刻，存在且仅存在一个HEAD。它可以是指向当前branch的head（比如，指向master，假如master是当前branch的话）；也可以不指向任何特定的branch（这叫做detached HEAD）。

系统会从你选择的head branch（在这里，是主题branch）的这个head开始匹配所有不包含在base branch中的commits，然后自动视作你的主题branch相对于base所增加的新特性，放进同一个Pull Request中提交。

六: Pull Request发送之后……

一旦你从自己的主题branch（例如fix-unicode-error）推送了一条Pull Request，那么在这条Pull Request被关闭之前，再次向这个branch里push代码，所有的commits都会被自动追加到这个Pull Request后面（不需要再另开Pull Request）。

这个功能尤其有用，比如你最初提交的Pull Request里存在某些问题，项目维护者要求你打回去修改；或者要求你给你的新feature添加一条相应的unit test（这种情况简直太常见了）。只要追加commits到你的这个主题branch中即可。

（题外话：如果原项目有Travis CI，那么它也会在每次追加push之后对Pull Request重新执行一遍测试）
*（针对项目维护者）cherry-pick、format-patch和am

这几条命令主要针对项目的维护者，稍微提一下。

git pull和git merge是GitHub上最常用的merge Pull Requests的方式，在命令行下merge之后，GitHub上面的PullRequest也会相应地自动关闭。

如果贡献者一次提交了多条commits，有些是维护者并不想要的，可以用这几条命令来选择性地手动commit。（这也适用于某些项目不是借助于GitHub的Pull Request，而是通过邮件列表和patch文件来进行协作开发的情形）

在这种情况下，GitHub上面的Pull Request并不能自动关闭，需要维护者手工操作。

七: Pull Request关闭之后

如果是已经被merge后关闭的Pull Request，你可以在页面的最下方找到一个“Delete this branch”的蓝色按钮。

这表明这个主题branch的历史使命已经完成（fix-unicode-error的commit已经被合并到主项目中），可以安全地从远程库中删除了。

在本地库中亦可删除这个branch：

$ git branch -d fix-unicode-error

反之，如果你的主题branch并没有被merge就被维护者关掉的话，你还可以继续再拿它来开新的Pull Request去骚扰主项目（�0�7▽‘ ）。
总结

在哪些情况下可以直接使用master branch来提交Pull Request：

你只想为主项目贡献某一处代码，贡献完自己的repo就可以扔的那种。
    你打算为主项目长期贡献代码，而且希望追随原项目的主线开发，不保留自己的特性。
    你打算为主项目长期贡献代码，默认master branch追随原项目主线，把自己的特性放到别的branch中。

在哪种情况下应该使用主题branch来提交Pull Request：

想用master branch完全来做自己的开发。在这种情形下：
        会从上游库合并更新，但是这些merge本身的commits显然不可能作为返还到上游库的Pull Request的一部分。
        存在自己的（未被merge或者不想被merge到上游库的）commits。

鉴于Git的分布式开发哲学，每一个库均可以看作是一个独立的项目，显然是后一种（为每一个新特性建立一个专门的主题branch来向主项目推送Pull Request）的贡献方式更可取。

注意事项

1、clone时一定要注意选择ssh协议的链接。否则可能导致clone失败，或者后续push失败

2、将公钥添加到github后，一定要更新自己当前的私钥（命令：ssh-add ~/.ssh/id_rsa），否则会push失败

3、当提交pull request后，对自己项目该分支做的任何修改都会pull request到原作者项目，直到pull request被接受。所以在pull request后，建议不要再对该分支进行修改，以免pull request过多，导致混乱。

参与github上开源项目的大致流程和注意事项（重要）

附件: