×

欢迎来到Github世界

96
YoKey
2017.07.20 08:21* 字数 2806
Github

前两天在团队中分享了该主题,反响不错,整理了下分享给小伙伴。


目录

  • 开始
  • 工欲善其事必先利其器 - 插件篇
  • Watch、Star、Fork
  • 项目菜单
  • 换个角度看世界 - Badge篇
  • Gist
  • 如何做好开源项目?
  • 一些建议

开始

Github是基于 Git 做版本控制的代码托管平台,同时也是全球最大的代(同)码(性)托(交)管(友)网站。

此外还有Bitbucket、 GitLab以及国内的Coding等等,感兴趣的同学可以阅读 这篇对比介绍


工欲善其事必先利其器 - 插件篇

关于Github的插件非常多,我仅推荐我目前在用的4个插件:

1、Hovercard

悬浮卡片工具: 鼠标悬停在Github上可点击的Links上(用户、仓库、issue、commit等等),会出现悬浮卡片显示相关信息


2、Dashboard Avatars

头像插件: 在GitHub Timeline上显示用户头像,可以更快速通过头像检索信息

3、Octotree

Octotree: 在Github页面添加侧边栏,在显示项目的目录结构, 必备

4、Zenhub

项目管理工具: 主要功能是对issue, PR进行管理,非常实用


Watch、Star、Fork

1、Watch

推荐阅读:如何正确接收 GitHub 的消息邮件

2、Star

理解为 关注、点赞,可在 "Your Stars" 里查看你Star过的项目

3、Fork

对当时原项目的拷贝,一般当你想给原项目提PR 或者想拓展维护一个属于自己项目时,使用Fork。

鉴于Fork的该特性,不建议把Fork当作Star来使用。

更详细的讲解,可看这篇文章:如何用好 github 中的 watch、star、fork


项目菜单

1、Code

可以理解为项目主页,包括代码、README、项目介绍、分支情况、Release情况、贡献者等等

2、Issues

对项目的建议、BUG、疑问,可以通过创建issue来提给项目作者。

提issue前,先查看项目中是否有:CONTRIBUTING.mdISSUE_TEMPLATE.md,若有则先阅读对Issue或者Issue的格式是否有要求,根据要求提Issue。 例: OkHttp的ISSUE_TEMPLATE

PS: 一般CONTRIBUTING.md、ISSUE_TEMPLATE.md、PULL_REQUEST_TEMPLATE.md 会放在项目根目录或.github目录下

3、PR

Pull Request,类似Gitlab中的MR(Merge Request),你不可能直接更改原项目的代码,而是通过fork进行更改,然后通过PR提交给原作者,原作者认为你的PR没问题则会merge你的PR,merge后你更改的代码就会体现到原项目中。 具体可看这篇文章:GitHub 的 Pull Request 是指什么意思?

同样,提PR前,先查看项目中的CONTRIBUTING.mdPULL_REQUEST_TEMPLATE.md

这里有一篇提PR的文章:如何提PR?

4、Projects

用于项目管理,可管理Issue, PR, Notes,推荐用来管理Notes,TODO等等

对于Issue,PR推荐使用Zenhub插件协助管理(上面插件篇 有介绍)

5、WIKI

项目文档,具体介绍、使用可看官方教程

一般来说,如果你的项目 使用说明较复杂,可以考虑放到wiki中维护,保持README的简洁

6、Insight

  • Community:(仅自己的项目有该项菜单)帮助开发者更好的贡献代码,检查清单包括4个部分:READMECode of conductContributingLicense

    其中:

    Code of conduct: 用于描述代码规范,对于Android更建议使用checkstyle来约束代码规范

    Contributing:描述提PR、issue时的规范

    License: 下面 Badge篇 会有相关介绍

  • Pulse: 显示近期项目的RP、Issue情况

  • Graphs : 各种数据(contributors、commit、fork、访问量等等)的图表展示


换个角度看世界 - Badge篇

我们会看到很多开源项目的README中,有很多好看的Badge,不仅看起来美观,同时通过Badge告知使用者项目的各种状态。

下面介绍一些常见的Badge,并从Badge角度触发,介绍相关内容

1、CI(持续集成)

实时展示最近的持续集成结果,对于Github上的开源项目,最流行的是travis-ci,它可以持续构建项目,能够测试和部署,对于开源项目完全免费,集成也非常方便 ,在项目中以.travis.yml描述构建任务

比如当你push、merge、打tag时,就会在几分钟内开始按照你的要求测试部署你的项目,如果构建成功,会实时显示


CI可以做很多事: 自动运行单元测试, 打Tag时自动构建APK并上传到内测分发平台(fir/蒲公英)或者 上传到Maven等等。

这篇文章介绍集成travis-ci: 如何简单入门持续集成( Travis-CI )

Badge可通过构建结果中获取

2、单元测试



展示单元测试覆盖情况,平台有:codecovcoveralls等等,推荐codecov,UI美观、流行,它们是开源的测试结果展示平台,将测试结果可视化。

如果你集成了travis-ci,并且写了单元测试,推荐集成codecov

Badge可通过项目设置列表里获取

3、推广



比如Android开源项目集合网站:Android Arsenal,可以在这里推广你的项目,该网站同时会对不同项目进行了分类,也是一个开源项目搜索网站

Badge可通过项目主页Badge菜单中获取

4、版本-项目管理工具

实时展示当前最新的最新Release版本,方便开发者快速知晓当前项目的最新版本。

一般我们的开源项目为方便的提供给别人使用,会上传到一些项目管理工具上,比如
Maven


Gem


CocoaPods


  • 上传你的项目到项目管理工具

    以Android为例,一般我们会上传到Bintray或者Jitpack,这里有一份简单易懂的教程
    Bintray



    Jitpack


    总体来说:

    1、上传到Jitpack 非常非常简单,但是需要额外添加maven { url 'https://jitpack.io' },而上传到Bintray相比较之下非常繁琐,尤其第一次上传。

    2、Bintray提供了完善了管理后台,可以单独下载javadoc、aar,查看近期项目被compile拉取的图表信息(拉取次数、版本分布、全球分布情况等等)

Bintray-Statistics

Badge通过相关平台的主页获取

5、License


主流开源协议:

  • Apache V2
  • MIT
  • GPL (v2,v3)
  • BSD

区别附一张阮一峰博客的讲解图:

License

Badge可直接拷贝图片链接即可

6、Gitter


开源世界的聊天社区,一些开源项目会选择在Giiter里开放聊天社区,比如RxJava的Gitter

Badge:Gitter的Github帐号会自动fork你的项目并提一个 添加Badge的PR

7、其它

Badge还有很多,这里不再介绍,建议挑选几个对项目最有用的Badge展示。

附:生成Badge的网站Shields


Gist

gist是一个分享平台,但是其实也可以分享代码、 笔记、文章等等,它的不同之处在于具有版本管理功能、支持多种写作格式等等。

对于程序猿,我们最多使用的是代码片段功能。比如我们提一个Issue时,我们想把自己的代码给作者看,此时gist是非常适合的方式:将你的代码片段放到gist,再将地址贴到issue上。

详细的介绍可以看下这篇文章:如何看待 Github Gist这个服务,怎样更好的利用?


如何做好开源项目?

  • 持续维护

    持续维护项目是非常必要的,跟进issue,是BUG就修复,是建议就思考,从使用者角度来看,我们会更倾向使用短期还在维护的项目,而不是a years ago这样的项目。


    用数据来说话,从Bintray的后台来看,当发布新版本后,新用户的数量上升明显,Github的Star也上升明显。

    另外如果精力有限,也可以招募开发者来共同维护。

  • 抓住痛点

    可以把开源项目看作是一个产品,使用者就是用户,而你作为作者就是PD兼PM,你推出一个产品(开源项目),解决了一些痛点,而用户会反馈一些建议、BUG,作为PD你要根据建议去设计更好的产品,作为PM要去修复这些BUG,并根据新需求去维护这个项目(产品)。

所以做好开源项目本质就是做一个好的产品:解决用户的痛点,容易被使用,解决问题简单高效。

  • 推广

    ​虽说是金子总会发光的,但是发光没人看也是没用的。

    ​在前期,适当推广自己的项目也是必要的,通过写作平台、技术博客、开源集合网站等平台都可以 。

最重要的我想说,不要报着功利心去做开源项目,应当对技术保持纯粹的热情,平常心很重要。


一些建议

  • 单元测试

    如果可能的话,尽量写单测,并持续维护单测。这会在你以后维护项目时省去大把时间,尤其是重构某个模块时,你可以放心大胆的重构,在单侧覆盖率较高的情况下,跑过了单测,这次重构基本就是安全的。

  • Issue - Label

    为你的issue添加Label,对一些经典、常见的issue打上Label,这样便于你以及开发者引用、查找。

当然对一些经常被问及的issue,也许把相关回答维护到wiki上更合适

  • SNAPSHOT版本

    对于大版本号的更新,建议先放出SNAPSHOT版本,因为大版本伴随着比较大的改动,提供SNAPSHOT版本给愿意尝鲜的开发者,可以帮你快速反馈问题,稳定后再Release正式版。


最后

我想我们都多多少少在使用别人的开源库,也许你现在可以考虑加入到开源的队伍中了,贡献自己的一份力量,从New repository开始吧!

感受分享的快乐,欢迎来到Github的世界 :)

随笔
Web note ad 1