github入门训练营[6]-参与开源的正确姿势

, , ,

尽管造轮子和参与开源并不能表明一个人的技术能力和水平，但参与开源确实是一个人对技术态度和兴趣的体现，因此很多招聘要求上都会有”Github Star过百”的要求。

对于工程师来说，的确应该多多关注社区和参与开源项目，保持对新技术的关注和探索。本文我们就讲下如何进行参与github上的开源项目开发。

github常用地址

github上的organization

如果你是一个团队，而不是一个个人。团队有一些项目要开源，则可以在github创建一个组织账号，在该组织下进行仓库的创建、修改、删除等管理。比如著名的 Vue.js 就是自己建立了一个组织账号，所有项目都放在该组织下面.

社区角色

  • 所有者（Owner）：即创建该项目且在他们Github账户上有该项目的用户或组织。 对于github的组织账户来说，组织下的所有人员People也可以设置为owner(对组织全部的权限)或Member(组织的普通成员, 只能看到自己该看到的项目)
  • 维护者和协作者（Maintainers and Collaborators）： 致力于一个项目并促进该项目发展的用户。通常所有者和维护者是同一个用户或组织，他们对项目库都有写的权限。（在一个github仓库项目里的Setting里可以设置这个项目的协作者和team，使他们可以对项目push代码）
  • 贡献者（Contributors）：每一个对该项目发出过pull request并合并到项目中的用户都是贡献者。
  • 社区成员（Community Members）：即那些经常使用且非常关心该项目的用户，他们在讨论功能特征和pull request上非常活跃；比如在issue上参加了讨论。

在一个项目仓库的Setting里面可以给项目添加协作者，给项目添加协作者或协作team的时候，可以设置 Admin, Write, Read 三种权限。

  • Admin, 能克隆、push代码. 由于是仓库管理员，所以还能在Setting里继续添加协作者
  • Write, 能clone、push代码
  • Read, 仅仅能读和克隆这个仓库

对于项目的核心成员，集中式版本管理和分布式版本管理贡献代码的方式并没有多大差异（这里不要纠结个人使用层面的差异，只谈论为仓库贡献代码的方式）。但对于非项目核心成员来说，集中式的版本管理就非常痛苦了，因为他们找不到方式来提交自己的代码（请忽略低效的发邮件补丁吧……）。然而分布式版本管理则解决了这个问题：非项目核心成员可以克隆仓库，这样就得到了一个自己具有完全读写权限的仓库，贡献的代码可以完全同步到这个具有完全读写权限的仓库中。

开源规范

在github的项目设置里有 community 选项，会提示你的项目缺少哪些开源标准文件:
![github项目设置]https://img.cuiyongjian.com/blog/githubsetting-community.png

  • Readme
    几乎所有的Github项目都包含一个README.md 文件。readme提供了该项目的一个概览及关于如何使用、构建甚至如何贡献于一个项目的相关细节。
  • Contributing
    项目和项目维护者不同，所以每个项目所期望的作贡献的最佳方法也会有所不同。一定要注意一个标注为CONTRIBUTING的文档，Contributing文档详细描述了一个项目的维护者希望看到贡献的补丁或功能应该符合怎样的规格。这可能包含要写什么测试，代码语法规范或补丁集中的区域。
  • License
    一个LICENSE文件当然就是该项目的许可证了。一个开源项目的license会告诉用户他们能做和不能做的（例如使用、修改、重新发布），及告诉贡献者他们允许其他人做的。有许多的办法对开源项目加上许可证，你可以在choosealicense.com读到更多的关于每个许可证的含义。
  • Documentation and Wikis
    许多大型项目有的不只有一个readme来指导人么如何使用他们的项目。在这种情况下你通常能够发现一个指向库中名为“docs”的另一个文件或文件夹的链接。

如果文档确实很多，你也可以使用github的WIKI, 例如百度的fecs便是使用wiki进行文档记录: FECS

为开源项目贡献代码

对于自己账号下的开源项目，你可以随意进行 pull 和 push。 但是对于别人的开源项目，你如果不是 协作者，则你是没有权限进行push的。在这种情况下 github社区通常要采用 Pull Request 的方式向别人贡献代码。发起 Pull Request 的具体步骤如下:

  1. 先在github上面点击 fork 把项目fork到自己的账户下

  2. 克隆自己账户下的本仓库到本地；然后通过添加为远程的方式在本地连接到原来的 upstream 库。经常从 upstream 库 pull in 改动以保持库最新，这样当你提交pull request时，就不大可能发生合并冲突了。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    # 列出当前远程仓库名称列表
    $ git remote -v
    origin  https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)
    origin  https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)
    # 增加一个叫做 upstream 的上游远程仓库名称
    $ git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git
    # 拉取这个远程仓库 upstream
    $ git fetch upstream
    # 此时你本地的upstream/master分支就是你fork的那个源仓库在你本地的版本，此时到自己的分支下merge一下这个upstream分支即可
    $ git checkout master
    $ git merge upstream/master

  3. 在你开发过程中，你不断将代码提交到自己本地的master分支
  4. 等到你希望把自己的修改提交给原作者的仓库时，你需要在自己的仓库的github页面里点击pull Request 发起一个 pull request请求
  5. 作者会收到这个请求，并查看你的修改或进行讨论，并最终同意merge到他的仓库分支上

给开源项目提bug或意见

如果你发现了你正在使用的项目中的一个bug（但是你不知道怎么去修复它），或对文档有不解或对项目有疑问—那么创建一个话题(Issue)吧！这非常容易且一般你不管创建什么话题，你都可能不是唯一一个出现该问题的人，所以其他人可能会发现你的话题很有帮助.

提出Issue时，最好按照下面的要求:

  • 在建话题之前检查已有的话题：话题重复对双方都无利，所以搜索整个正开放和已关闭的话题以检查你遇到的问题是否已经有人解决了。
  • 务必对自己的问题有清晰的认识：期望的结果是什么？然而却发生了什么？ 详细描述其他人如何重现该问题。
  • 在像JSFiddle 或 CodePen 类似的平台上重现该问题并给出问题demo的链接。
  • 包含一些系统相关的细节，比如用的什么浏览器、库或操作系统及版本号。
  • 在你的话题或在 Gist 里贴出你的错误输出或日志。如果在话题里贴出来，请用三个反引号包围起来(代码高亮)使得能够良好的呈现给大家

pull request 和 merge request的区别

为了让非核心成员提交的代码被核心成员接纳，非核心成员会向核心成员提出“申请（Request）”去自己的仓库指定分支中“拉取(pull)”最新的修改，这便是 Pull Request 的来源。

那么 Merge Request 又是什么呢？GitLab 对此的解释是——一样的，没有区别。Merge 只是在强调最后的那个动作“合并（Merge）”。

GitHub、Bitbucket 和码云（Gitee.com）选择 Pull Request 作为这项功能的名称
GitLab 和 Gitorious 选择 Merge Request 作为这项功能的名称

refer

pullrequest与mergerequest的区别