参与 GitHub 开源项目

GitHub 是一个基于 git 的代码托管平台,越来越多的个人和公司纷纷加入到 Github 的大家族里来,为开源事业尽一份自己的力量。对于个人来讲,把自己的项目托管到 Github 上并不表示你参与了 Github 开源项目,只能说你开源了自己的项目,可以任别人自由下载。那么该如何参与 Github 的开源项目呢?最近自己参与了一个地图插件项目,在此把开源的概念和参与的过程给大家分享一下。

关于项目成员

一般来说,每个项目通常由一个社区来维护,社区又由不同角色的用户组成。

  • Owner:所有者,即创建该项目且在他们 Github 账户上有该项目的用户或组织。
  • Maintainers and Collaborators:维护者和协作者, 致力于一个项目并促进该项目发展的用户。通常所有者和维护者是同一个用户或组织,他们对项目库都有写入的权限。
  • Contributors:贡献者,每一个对该项目发出过 pull request 并合并到项目中的用户都是贡献者。
  • Community Members:社区成员,即那些经常使用且非常关心该项目的用户,他们在讨论功能特征和 pull request 上非常活跃。

项目包含的文件

一个典型的开源项目应该包含的文件:

  • Readme:几乎所有的 Github 项目都包含一个 README.md 文件。自述文件提供了该项目从开始到如何使用、构建以及如何贡献于一个项目的相关细节。
  • Contributing:项目和项目维护者不同,所以每个项目所期望的作贡献的最佳方法也会有所不同。务必要打开并阅读一个名为 CONTRIBUTING 的文档,Contributing 文档详细描述了一个项目的维护者希望看到贡献的是什么样的补丁或功能。这可能包含要写什么测试,代码语法风格或补丁关注的区域。
  • License: LICENSE 文件是该项目的许可证书。一个开源项目的许可证书会告诉用户他们能做和不能做的(例如使用、修改、重新发布),以及他们允许其他人做的内容。有许多的办法对开源项目加上许可证,你可以在 choosealicense.com 读到更多的关于每个许可证的含义。
  • Documentation and Wikis:许多大型项目有的不只有一个自述文件来指导人么如何使用他们的项目。在这种情况下你通常能够发现一个指向库中名为“docs”的另一个文件或文件夹的链接。

参与项目

首先我们要参与的项目是 jvectormap,一个JS地图插件,我们要做的工作是调整目录结构和修改一些Bug,然后进行 pull request。步骤如下:

1. Fork 代码仓库

打开项目(https://github.com/bjornd/jvectormap),点击右上方 Fork 按钮,将这个项目 fork 到自己的账户下,然后你会发现自己的 repositories 中多了这个项目(https://github.com/alei817927/jvectormap)。为了方便后面描述,我们把原项目简称为A,自己 fork 的项目简称B。

2. 克隆项目

把B克隆到本地(参考 git 详细用法):

$ git clone https://github.com/alei817927/jvectormap

克隆完毕,但是还有些问题。我们看一下项目的分支:

$ git branch -a
* master
 remotes/origin/HEAD -> origin/master
 remotes/origin/develop
 remotes/origin/master

发现目前项目对应的分支是 master ,而 jvectormap 开发的分支是 develop,我们需要切换到 develop 分支上去并且把这里面的内容拉下来:

# 创建并切换分支
$ git checkout -b develop
# 重新设置默认跟踪的分支
$ git branch --set-upstream-to=origin/develop
$ git branch -a
* develop
  master
  remotes/origin/HEAD -> origin/master
  remotes/origin/develop
  remotes/origin/master
# 开始拉取develop里面的内容吧
$ git pull

还有另一种方式:

$ mkdir jvectormap && cd jvectormap
$ git init
$ git remote add origin https://github.com/alei817927/jvectormap
$ git remote -v
origin  https://github.com/alei817927/jvectormap (fetch)
origin  https://github.com/alei817927/jvectormap (push)
$ git fetch origin
remote: Counting objects: 1415, done.
remote: Compressing objects: 100% (542/542), done.
rRemote: Total 1415 (delta 844), reused 1415 (delta 844)
Receiving objects: 100% (1415/1415), 2.89 MiB | 505.00 KiB/s, done.
Resolving deltas: 100% (844/844), done.
From https://github.com/alei817927/jvectormap
 * [new branch]      develop    -> origin/develop
 * [new branch]      master     -> origin/master
 * [new tag]         2.0.0      -> 2.0.0
 ...
# 看看远程分支
$ git branch -r
  remotes/origin/develop
  remotes/origin/master
$ git pull origin develop
From https://github.com/alei817927/jvectormap
 * branch            develop    -> FETCH_HEAD
# 本地和远程分支
$ git branch -a
* develop
  remotes/origin/develop
  remotes/origin/master
# 重新设置默认跟踪的分支
$ git branch --set-upstream-to=origin/develop

现在你可以按照自己的想法修改项目了,修改后提交至 origin/develop。

3. 设置A和B同步

在做 pull request 之前,通常需要把A上面最新的内容 merge 到B上,现在我们增加一个分支 upstream 来连接A。如果A没有改动,这步可以暂时忽略。

$ git remote add upstream https://github.com/bjornd/jvectormap
$ git branch -a
* develop
  remotes/origin/develop
  remotes/origin/master
  remotes/upstream/develop
  remotes/upstream/master
$ git fetch upstream
$ git merge upstream/develop
# merge后把本地的改动推送到远程仓库上去
$ git add .
$ git commit -m "merge something"
$ git push origin develop

4. 发起pull request

打开B(https://github.com/alei817927/jvectormap),按照下面步骤操作:

  • 点击右侧链接 Pull Requests 发起请求;
  • 点击 new pull request
  • 点击 Edit 修改 develop 分支,此时你可以查看改动的内容;
  • 点击 Create pull request,然后输入标题和你更改的信息;
  • 点击 Send pull request 发送请求。

此时你已完成了操作,剩下的就是等待维护者或协作者来操作了。

注意事项

  • 在参与开源项目时,一定要认真阅读该项目的 Contributing 文档,按照要求进行开发;
  • 务必清楚所出现的问题以及如何重现该问题,明确你的工作对该项目有何帮助;
  • 对于自己所做的改动要认真做好测试,确保你的改动不会破坏现有项目;

结束语

在你发起 Pull Requests 后,大家可能会针对你所作出的改动进行探讨,任何社区成员都可以参与进来,不过最终由维护者做出决定。如果你的 pull request 被合并了,那么恭喜你。如果没有被合并,也没关系,可能你的改动不是维护者所期望的或者有更好的解决方式。无论什么结果,我们都要有平和开放的心态,为开源事业做出自己的贡献。

发表评论