数据API 案例 开发者 关于
掌握聚合最新动态了解行业最新趋势
API接口,开发服务,免费咨询服务
新闻动态 > 媒体报道

如何发起一个高质量的github开源项目

 创建项目

在 github 上新建一个空项目,然后 clone 到本地,进行开发。开发好了之后,将代码 push 到 github 上。

# clone 代码到本地
git clone git@githbu.com:username/repos.gi

t# 进行开开发...

# 提交代码
git add .
git commit -m "initial commit"
# 推送代码git push -u origin master

npm占坑  

因为是前端的项目,安装依赖通常有 npm、bower 两种,所以确定好项目名称之后,请到 npm 上占坑。

首先你需要在 https://npmjs.com 上注册一个帐号,填写用户名、邮箱、密码。

1287-640.jpg.jpg

然后在本地的终端,通过 npm adduser 命令,添加你的帐号信息,需要输入刚才注册帐号时的用户名、邮箱和密码。

1288-640.jpg.png

然后确保项目中的 package.json 文件,包含了必要的信息,例如项目名称、版本、主页、作者、协议、入口文件等。以 WeUI 项目为例:

{    
    "name": "weui",    
    "version": "0.4.0",    
    "description": "A UI library by WeChat official design team, includes the most useful widgets/modules in mobile web applications.",    
    "keywords": ["weui","wechat","weixin","css","less","mobile"],    
    "style": "dist/style/weui.css",    
    "less": "src/style/weui.less",    
    "main": "dist/style/weui.css",    
    "scripts": {        
        "start": "gulp -ws",
        "test": "gulp release"
    },    
    "author": "wechat ui team",    
    "repository": {        
        "type": "git",        
        "url": "https://github.com/weui/weui.git"
    },    
    "homepage": "https://github.com/weui/weui",    
    "bugs": {        
        "url": "https://github.com/weui/weui/issues"
    },    
    "license": "MIT",    
    "devDependencies": {}
}

然后使用 npm publish 命令,将项目发布到 npm 上,供其他人下载使用。

npm publish .

发布成功之后,你就可以在 https://www.npmjs.com/package/packagename 是看到项目信息了。其他人可以通过 npm install <packagename> 命令来下载你的项目。

Bower占坑

bower 是一个可选的方案,因为这个项目的前景不明朗,由于 bower 本身的不少缺点,很多著名项目明确表示不支持 bower,而 npm 有统一前端包管理的趋势。不过对于我们普通项目来说,只是多一个下载渠道而已,用起来并无大碍。那么来看看发布一个 bower 项目需要什么步骤呢?

  • 在项目的根目录,新建 bower.json 描述文件,字段与 package.json 类似,包含名称、版本信息、作者、主文件等字段;以 WeUI 为例:

{    
"name": "weui",    
"repository": {        
"type": "git",       
"url": "https://github.com/weui/weui.git"
    
  },    
  "description": "wechat mobile ui",    
  "main": "dist/style/weui.css",    
  "version": "0.4.0",    
  "authors": ["wechat ui team"],    
  "license": "MIT",    
  "keywords": ["wechat","weixin","mobile","ui"],    
  "homepage": "https://github.com/weui/weui",    
  "ignore": []
}
  • 运行注册命令:

bower register example git://github.com/user/packagename.git

就是这么简单!然后就可以通过 bower install <packagename> 的命令来下载了。需要注意的是,如果 github 上没有打 tag,就会拉取 master 分支的最新代码,如果有打 tag,就会拉取最新打 tag 的版本。tag 的命名方式参考 semver

README文档

README 文档很重要,开发者一进来,看到的就是你的 README 文档。所以 README 写得好不好,很重要。通常来讲,README 可以从以下几个方面来写:

  • 项目简洁的介绍或 slogan

  • 可供访问的演示地址

  • 简单的上手文档

    • 如何通过 npm 、bower 等方式获取

    • 如何如何引用

    • 如何调用

  • 如果项目的 API 只有简单几个,文档可以直接写在 README

  • 开源协议

  • 贡献指南

  • 版本变更日志

开源License

选择开源 License 也是一个比较重要的步骤,因为这涉及到版权问题,以及使用者使用范围。

世界上有非常多的开源协议,例如我们经常看到的 GPL、BSD、MIT、Apache。 这里 license list 有各种非常详细的开源 License 的介绍。

如果你和我一样,多到不想看,那么就直接参考以下这张图吧:

1289-640.jpg.jpg

建议你在 README 文档中写明你使用哪种开源 License 的同时,给出 License 的链接,可以是公共的链接,如 https://opensource.org/licenses/MIT 也可以是放在你项目根目录的文件链接。

Wiki文档 

如果项目使用起来比较复杂,那么相应地说明文档也会变多。这时如果也直接堆砌到 README 中,就不太合适,推荐在 Wiki 中编辑。github 的 wiki 编辑功能还算过得去,能满足基本的需求。但是让我觉得不爽的是:

  • 编辑 wiki 时不能直接上传图片,需要跑到 issue 中上传好了得到链接,然后 copy 过去

  • 就一个 textarea,在编辑代码的时候感觉偏弱,因为不能按 Tab 缩进或 Shift + Tab 取消缩进

  • wiki 主页右侧的导航栏不能自定义,只能按照 wiki 页面的字母顺序出现

CONTRIBUTING  

既然是开源项目,那么通常都希望有更多的人参与进来。当别人需要给你的项目贡献时,如果有一个清晰的贡献指引,那么对其他开发者来说就会变得更顺利,对你来说也减少很多沟通麻烦。这里的贡献,不仅是指贡献代码,提出意见、建议、报告 bug 也算是贡献。

那么一般的 CONTRIBUTING 就应该需要包括:

  • 提出 issue 时的注意事项

    • 是否已经有人提过

    • 提出 issue 的格式

    • 如果是报告 bug,需要提供重现 bug 的条件

    • 如果问题得到解决,及时关闭 issue

    • 其他

  • 贡献代码时

    • 项目依赖的环境

    • 各个文件、目录是什么内容

    • 如何启动项目

    • 代码风格

    • 如何编译

    • 命名方式,驼峰、下划线还是短横线

    • 缩进,空格还是 Tab,2 个空格还是 4个空格

    • 单引号还是双引号

    • 大括号是在上一行还是另起一行

    • 其他

    • github 协作模式,在哪个分支开发,Pull Request 发送到哪个分支

    • 开发指引

    • 是否需要增加文档

    • 是否需要增加测试用例

    • 是否有覆盖率的要求

CHANGELOG 

事物都是发展的,有生命力的软件项目也一样,从简单到复杂,从有缺陷到完善。在项目的迭代过程中,为了他人清晰地了解不同版本,都要哪些变更,你需要维护好 CHANGELOG。

提交注释

日常的提交代码中,应该写好注释,而不是 “fix”、“bugfix”、“fixbug”、“update”、“最新变更”这种毫无意义的说明。一个好的注释通常包括:

  • 解决了什么问题

  • 新增了什么功能

  • 如果有相关的 issue,应该关联 issue id

版本变更日志

对于项目的使用者来说,会比较关心版本发布日志。版本变更日志通常包括:

  • 版本号

  • 发布时间

  • 修复了什么问题,关联 commit id

  • 新增了什么功能,关联 commit id

测试用例

为什么需要测试?你写一个 hello world,应该不会有什么 bug。但是项目大了,是人写出来的东西都会存在缺陷。因此,一个靠谱的项目,测试用例是必不可少的。以我浅薄的认知来看,写测试用例的好处有:

  • 发现已有的 bug

  • 防止修改代码时出现新 bug

  • 释放人力,不用每次都人肉测试

根据测试角度不同,前端项目的测试通常可以分为:

  • 单元测试(unit)

  • 端对端测试(e2e)

  • 人肉测试

单元测试,是粒度最小的一种测试,测试程序的每个小部件是否都正常工作。对应于前端,就是测试每个函数是否都正常。

端对端测试,就是模拟正常用户去使用程序,看看每个步骤是否都达到预期。前端代码的运行,依赖于浏览器环境,而市面上的浏览器众多,操作标准不同,Selenium server 就是抹平浏览器的差异,提供统一的接口,有不同的语言版本,Java、C#、Python、Ruby、JavaScript。有一个项目 Nightwatch.js,让我们可以通过 JavaScript 来操作浏览器进行测试,配上不同的驱动,我们可以从用户的角度,测试 Chrome、Firefox、IE、PhantomJS的表现。

人肉测试,就是人肉测试,一般是 UI 相关的项目才使用使用这种方式。目前我没有发现比较好的前端 UI 自动化测试方法,只能通过肉眼看。如果你知道有什么好方法,很期待推荐给我。

覆盖率 

测试用例是写了,但是怎样去衡量测试用例写得好不好呢?这可能就陷入死循环了,我需不需要去写测试用例的测试用例,去保证我的测试用例是 OK 的?这么干的话估计就没完没了了。

于是前辈们发明了一种衡量测试用例是否健壮的方式,覆盖率。

覆盖率通常包括:

  • 行覆盖率(line coverage):是否每一行都执行了

  • 函数覆盖率(function coverage):是否每个函数都调用了

  • 分支覆盖率(branch coverage):是否每个if代码块都执行了

  • 语句覆盖率(statement coverage):是否每个语句都执行了

前端领域,我们有覆盖率检测工具 istanbul。它可以帮你生成非常详细的覆盖率报告,具体使用方式可以参考它的文档。

持续集成

什么是持续集成?推荐阅读阮老师的文章 持续集成是什么? 。

github 上的开源项目,通常会选择 travis-ci。在项目的根目录新建 travis-ci 的配置文件 .travis.yml,根据你的实际情况编写配置。当有提交推送到 github 、有人发起 Pull Request 时,travis-ci 会自动运行你的测试用例,给出测试结果。

再补充一下,在 travis-ci 运行测试用例之后,怎样查看覆盖率报告呢?当然也有这样的服务 coveralls 。它有配套的 node 模块,当你在 travis-ci 运行完测试用例,用 istanbul 生成覆盖率报告,然后利用 coveralls 提供的 node 模块上传到它的服务器,就可以在线查看详细的覆盖率报告了。

例如,react-weui 的 .travis.yml 的配置如下:

language: node_jsnode_js:
  - stablescript:
  - npm test
  - npm run coverageafter_script:
    npm install coveralls && cat ./coverage/lcov.info | coveralls

最后

最后,为了提升项目的逼格,别忘了加上各种徽章。可以在这里 shields.io 挑选几个能够体现你身份的徽章,加在 README 前面。

原文来自: 腾讯课堂Coding学院

掌握聚合最新动态了解行业最新趋势
API接口,开发服务,免费咨询服务
新闻动态 > 媒体报道
如何发起一个高质量的github开源项目
发布:2017-04-24

 创建项目

在 github 上新建一个空项目,然后 clone 到本地,进行开发。开发好了之后,将代码 push 到 github 上。

# clone 代码到本地
git clone git@githbu.com:username/repos.gi

t# 进行开开发...

# 提交代码
git add .
git commit -m "initial commit"
# 推送代码git push -u origin master

npm占坑  

因为是前端的项目,安装依赖通常有 npm、bower 两种,所以确定好项目名称之后,请到 npm 上占坑。

首先你需要在 https://npmjs.com 上注册一个帐号,填写用户名、邮箱、密码。

1287-640.jpg.jpg

然后在本地的终端,通过 npm adduser 命令,添加你的帐号信息,需要输入刚才注册帐号时的用户名、邮箱和密码。

1288-640.jpg.png

然后确保项目中的 package.json 文件,包含了必要的信息,例如项目名称、版本、主页、作者、协议、入口文件等。以 WeUI 项目为例:

{    
    "name": "weui",    
    "version": "0.4.0",    
    "description": "A UI library by WeChat official design team, includes the most useful widgets/modules in mobile web applications.",    
    "keywords": ["weui","wechat","weixin","css","less","mobile"],    
    "style": "dist/style/weui.css",    
    "less": "src/style/weui.less",    
    "main": "dist/style/weui.css",    
    "scripts": {        
        "start": "gulp -ws",
        "test": "gulp release"
    },    
    "author": "wechat ui team",    
    "repository": {        
        "type": "git",        
        "url": "https://github.com/weui/weui.git"
    },    
    "homepage": "https://github.com/weui/weui",    
    "bugs": {        
        "url": "https://github.com/weui/weui/issues"
    },    
    "license": "MIT",    
    "devDependencies": {}
}

然后使用 npm publish 命令,将项目发布到 npm 上,供其他人下载使用。

npm publish .

发布成功之后,你就可以在 https://www.npmjs.com/package/packagename 是看到项目信息了。其他人可以通过 npm install <packagename> 命令来下载你的项目。

Bower占坑

bower 是一个可选的方案,因为这个项目的前景不明朗,由于 bower 本身的不少缺点,很多著名项目明确表示不支持 bower,而 npm 有统一前端包管理的趋势。不过对于我们普通项目来说,只是多一个下载渠道而已,用起来并无大碍。那么来看看发布一个 bower 项目需要什么步骤呢?

  • 在项目的根目录,新建 bower.json 描述文件,字段与 package.json 类似,包含名称、版本信息、作者、主文件等字段;以 WeUI 为例:

{    
"name": "weui",    
"repository": {        
"type": "git",       
"url": "https://github.com/weui/weui.git"
    
  },    
  "description": "wechat mobile ui",    
  "main": "dist/style/weui.css",    
  "version": "0.4.0",    
  "authors": ["wechat ui team"],    
  "license": "MIT",    
  "keywords": ["wechat","weixin","mobile","ui"],    
  "homepage": "https://github.com/weui/weui",    
  "ignore": []
}
  • 运行注册命令:

bower register example git://github.com/user/packagename.git

就是这么简单!然后就可以通过 bower install <packagename> 的命令来下载了。需要注意的是,如果 github 上没有打 tag,就会拉取 master 分支的最新代码,如果有打 tag,就会拉取最新打 tag 的版本。tag 的命名方式参考 semver

README文档

README 文档很重要,开发者一进来,看到的就是你的 README 文档。所以 README 写得好不好,很重要。通常来讲,README 可以从以下几个方面来写:

  • 项目简洁的介绍或 slogan

  • 可供访问的演示地址

  • 简单的上手文档

    • 如何通过 npm 、bower 等方式获取

    • 如何如何引用

    • 如何调用

  • 如果项目的 API 只有简单几个,文档可以直接写在 README

  • 开源协议

  • 贡献指南

  • 版本变更日志

开源License

选择开源 License 也是一个比较重要的步骤,因为这涉及到版权问题,以及使用者使用范围。

世界上有非常多的开源协议,例如我们经常看到的 GPL、BSD、MIT、Apache。 这里 license list 有各种非常详细的开源 License 的介绍。

如果你和我一样,多到不想看,那么就直接参考以下这张图吧:

1289-640.jpg.jpg

建议你在 README 文档中写明你使用哪种开源 License 的同时,给出 License 的链接,可以是公共的链接,如 https://opensource.org/licenses/MIT 也可以是放在你项目根目录的文件链接。

Wiki文档 

如果项目使用起来比较复杂,那么相应地说明文档也会变多。这时如果也直接堆砌到 README 中,就不太合适,推荐在 Wiki 中编辑。github 的 wiki 编辑功能还算过得去,能满足基本的需求。但是让我觉得不爽的是:

  • 编辑 wiki 时不能直接上传图片,需要跑到 issue 中上传好了得到链接,然后 copy 过去

  • 就一个 textarea,在编辑代码的时候感觉偏弱,因为不能按 Tab 缩进或 Shift + Tab 取消缩进

  • wiki 主页右侧的导航栏不能自定义,只能按照 wiki 页面的字母顺序出现

CONTRIBUTING  

既然是开源项目,那么通常都希望有更多的人参与进来。当别人需要给你的项目贡献时,如果有一个清晰的贡献指引,那么对其他开发者来说就会变得更顺利,对你来说也减少很多沟通麻烦。这里的贡献,不仅是指贡献代码,提出意见、建议、报告 bug 也算是贡献。

那么一般的 CONTRIBUTING 就应该需要包括:

  • 提出 issue 时的注意事项

    • 是否已经有人提过

    • 提出 issue 的格式

    • 如果是报告 bug,需要提供重现 bug 的条件

    • 如果问题得到解决,及时关闭 issue

    • 其他

  • 贡献代码时

    • 项目依赖的环境

    • 各个文件、目录是什么内容

    • 如何启动项目

    • 代码风格

    • 如何编译

    • 命名方式,驼峰、下划线还是短横线

    • 缩进,空格还是 Tab,2 个空格还是 4个空格

    • 单引号还是双引号

    • 大括号是在上一行还是另起一行

    • 其他

    • github 协作模式,在哪个分支开发,Pull Request 发送到哪个分支

    • 开发指引

    • 是否需要增加文档

    • 是否需要增加测试用例

    • 是否有覆盖率的要求

CHANGELOG 

事物都是发展的,有生命力的软件项目也一样,从简单到复杂,从有缺陷到完善。在项目的迭代过程中,为了他人清晰地了解不同版本,都要哪些变更,你需要维护好 CHANGELOG。

提交注释

日常的提交代码中,应该写好注释,而不是 “fix”、“bugfix”、“fixbug”、“update”、“最新变更”这种毫无意义的说明。一个好的注释通常包括:

  • 解决了什么问题

  • 新增了什么功能

  • 如果有相关的 issue,应该关联 issue id

版本变更日志

对于项目的使用者来说,会比较关心版本发布日志。版本变更日志通常包括:

  • 版本号

  • 发布时间

  • 修复了什么问题,关联 commit id

  • 新增了什么功能,关联 commit id

测试用例

为什么需要测试?你写一个 hello world,应该不会有什么 bug。但是项目大了,是人写出来的东西都会存在缺陷。因此,一个靠谱的项目,测试用例是必不可少的。以我浅薄的认知来看,写测试用例的好处有:

  • 发现已有的 bug

  • 防止修改代码时出现新 bug

  • 释放人力,不用每次都人肉测试

根据测试角度不同,前端项目的测试通常可以分为:

  • 单元测试(unit)

  • 端对端测试(e2e)

  • 人肉测试

单元测试,是粒度最小的一种测试,测试程序的每个小部件是否都正常工作。对应于前端,就是测试每个函数是否都正常。

端对端测试,就是模拟正常用户去使用程序,看看每个步骤是否都达到预期。前端代码的运行,依赖于浏览器环境,而市面上的浏览器众多,操作标准不同,Selenium server 就是抹平浏览器的差异,提供统一的接口,有不同的语言版本,Java、C#、Python、Ruby、JavaScript。有一个项目 Nightwatch.js,让我们可以通过 JavaScript 来操作浏览器进行测试,配上不同的驱动,我们可以从用户的角度,测试 Chrome、Firefox、IE、PhantomJS的表现。

人肉测试,就是人肉测试,一般是 UI 相关的项目才使用使用这种方式。目前我没有发现比较好的前端 UI 自动化测试方法,只能通过肉眼看。如果你知道有什么好方法,很期待推荐给我。

覆盖率 

测试用例是写了,但是怎样去衡量测试用例写得好不好呢?这可能就陷入死循环了,我需不需要去写测试用例的测试用例,去保证我的测试用例是 OK 的?这么干的话估计就没完没了了。

于是前辈们发明了一种衡量测试用例是否健壮的方式,覆盖率。

覆盖率通常包括:

  • 行覆盖率(line coverage):是否每一行都执行了

  • 函数覆盖率(function coverage):是否每个函数都调用了

  • 分支覆盖率(branch coverage):是否每个if代码块都执行了

  • 语句覆盖率(statement coverage):是否每个语句都执行了

前端领域,我们有覆盖率检测工具 istanbul。它可以帮你生成非常详细的覆盖率报告,具体使用方式可以参考它的文档。

持续集成

什么是持续集成?推荐阅读阮老师的文章 持续集成是什么? 。

github 上的开源项目,通常会选择 travis-ci。在项目的根目录新建 travis-ci 的配置文件 .travis.yml,根据你的实际情况编写配置。当有提交推送到 github 、有人发起 Pull Request 时,travis-ci 会自动运行你的测试用例,给出测试结果。

再补充一下,在 travis-ci 运行测试用例之后,怎样查看覆盖率报告呢?当然也有这样的服务 coveralls 。它有配套的 node 模块,当你在 travis-ci 运行完测试用例,用 istanbul 生成覆盖率报告,然后利用 coveralls 提供的 node 模块上传到它的服务器,就可以在线查看详细的覆盖率报告了。

例如,react-weui 的 .travis.yml 的配置如下:

language: node_jsnode_js:
  - stablescript:
  - npm test
  - npm run coverageafter_script:
    npm install coveralls && cat ./coverage/lcov.info | coveralls

最后

最后,为了提升项目的逼格,别忘了加上各种徽章。可以在这里 shields.io 挑选几个能够体现你身份的徽章,加在 README 前面。

原文来自: 腾讯课堂Coding学院

×
企业用户认证,
可获得1000次免费调用
注册登录 > 企业账户认证 > 领取接口包
企业用户认证领取接口包 立即领取
× 企业用户认证,
可获得1000次免费调用,立即领取>
数 据 驱 动 未 来
Data Drives The Future