一个开源项目,如何在别人一眼看上去就觉得靠谱,有点逼格。

这是一个值得深思的问题。可能代码不咋地,需要一些东西来装饰。

如果你是开源社区的大牛

那还说什么,强如tj大神,开个仓库就是热门项目

Logo

Logo即是商标,容易让人记住。也有的彰显着项目用途

比如这个趣图(来自github.com/tj/node-prune)

huge

Badge

徽章能一眼反映出一个开源项目的状态。比如,测试是否通过,代码覆盖率,依赖关系,兼容性,当前版本,许可文件等

比如github.com/vuejs/vue

Build Status Coverage Status Downloads Version License Chat
Sauce Test Status

你可以从shields.io自定义自己想要的徽章

大多数你需要的,有已经定义好了

Github的issue/pull request模板

项目根目录下,应该有个.github文件夹

  • ISSUE_TEMPLATE.md (issue模板)
**I'm submitting a ...**  (check one with "x")

- [ ] bug report => search github for a similar issue or PR before submitting
- [ ] feature request
- [ ] support request

**Current behavior**


**Expected behavior**


**More detail**


**Please tell us about your environment:**
  • PULL_REQUEST_TEMPLATE.md (pull request模板)
**Please check if the PR fulfills these requirements**
- [ ] The commit message follows **commit message standard**
- [ ] Tests for the changes have been added (for bug fixes / features)
- [ ] Docs have been added / updated (for bug fixes / features)


**What kind of change does this PR introduce?** (check one with "x")

[ ] Bugfix
[ ] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Test change
[ ] Chore change
[ ] Update Document
[ ] Other... Please describe:

**What is the current behavior?** (You can also link to an open issue here)



**What is the new behavior?**



**Does this PR introduce a breaking change?** (check one with "x")

[ ] Yes
[ ] No


If this PR contains a breaking change, please describe the impact and migration path for existing applications: ...


**Other information**:

配合CI工具

Github有开放API,可以接入各种好玩,实用的bot

Travis

Travis是一个自动化测试的CI工具,你每push一次,在travis平台会运行一次test。然后把测试结果通过邮件的形式告知你。

它还可以生成一个漂亮的徽章,如这样Build Status

以为Go项目为例,这是.travis.yml文件,放置在项目根目录下

# .travis.yml
language: go
sudo: false

os:
  - linux

go: master

script:
  - go test -v

Coveralls

Coveralls是一个代码覆盖率的分析平台。

使用工具生产覆盖率的文件,然后提交给Coveralls平台。当然可以结合travis使用。

travis每运行一次test之后,可以把test的结果报告发送给Coveralls。

Coveralls同样也会生成一个漂亮的徽章,如这样Coverage Status

要使用它,仅需要2个步骤

  1. 在Coveralls平台添加项目
  2. 修改.travis.yml配置,然后提交

继续以Go为例。

# .travis.yml
language: go
sudo: false

os:
  - linux

go: master

before_script:
  # 加载依赖
  - go get golang.org/x/tools/cmd/cover
  - go get github.com/mattn/goveralls

script:
  - go test -v -covermode=count -coverprofile=coverage.out  # 运行测试,并且生成测试报告
  - $HOME/gopath/bin/goveralls -coverprofile=coverage.out -service=travis-ci  # 将测试报告提交给Coveralls

new-issue-welcome

这个CI工具会在其他人,在项目第一次发起issue的时候,bot会自动回复。一个友好的问题

screen shot 2017-07-17 at 1 31 50 pm

request-info

当有一个没有任何描述的issue产生时,bot会自动回复,提示创建者提供更多的信息

screen shot 2017-07-07 at 3 32 01 pm

stale

当一个issue或PR很久没有回复的时候,这个bot会帮助你把它关掉

Document

一般而言,一个小功能的库,是不需要文档的,只需要在README里面声明调用方法。

当项目是一个复杂的库/框架/工具的时候。有能就需要提供一个详细的文档。

Github提供了gh-pages分支用以存放文档,或者在master分支下的docs文件夹,在项目设置里面设置好即可

有简单粗暴型,直接以Markdown作为文档。这里有个思路很清晰的md文档API

有文艺型,通过Hexo等静态文件生成器,把Markdown文档转换为HTML。然后部署到gh-pages

有懒人型,使用docsify动态解析Markdown文件,放在项目的docs目录下,然后渲染。

当然文档不是必须的,如果简单明了的源码或者IDE提示,那么就不需要文档。

有些时候增加文档,反而增加了维护文档的成本。

最后

这是我的根项目github.com/axetroy/Github

里面基本上包含了上面的功能,没创建一个新仓库,都是从这里面clone更改的,避免重复创建文件。

也建议各位这样做,保持良好的仓库编辑习惯。