如何发起一个高质量的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 上注册一个帐号，填写用户名、邮箱、密码。

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

然后确保项目中的 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 的介绍。

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

建议你在 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学院

声明：所有来源为“聚合数据”的内容信息，未经本网许可，不得转载！如对内容有异议或投诉，请与我们联系。邮箱：marketing@think-land.com