怎样让开源项目看起来“高大上”

时间 2019-12-04

标签怎样开源项目看起来高大繁體版

原文原文链接

为了不重复造轮子，咱们每每会借助开源的项目实现一些功能。不少时候，选择使用哪个开源项目就像选择男、女友同样，当然内在很重要，可是眼缘也很关键，只有看对了眼，才会进一步地了解。做为开源项目的开发者，固然是但愿本身写出来的成果能被更多的人尝试使用，因此这篇文章主要谈一谈怎样让开源项目看起来“高大上”，从而让别人有使用的冲动。html

首先要弄清楚一个问题：怎样的开源项目才算“高大上”呢？这里举出两个例子，一个是在 2017 年愈来愈火的前端框架 Vue，还有一个是我所在团队大神 avwo 开源的 web 调试代理工具 whistle，你们能够去他们的 Github 地址感觉一下，下面展现一下他们 Readme 的开头部分：前端

在我我的看来，一个“高大上”的 Github 上的开源项目应该知足这些条件：vue

一句话说明项目的功能；
有相对完善的测试用例和较高的代码覆盖率；
经过徽章明确地指出项目的兼容性、最新版本、被使用状况、License 等；
有详尽地 CHANGELOG 或者 release notes，也就是更新说明；
有简介、明了的 commit 信息；
提供 discord、Telegram（国外）、QQ 群或者微信群（国内）等供使用者交流的地方；
利用 Github 能力提供 issue 和 pull request 的模板。

注意：上述排名分前后，若是有能力提供有一个美观、独特的 Logo，固然更好 🙃。ios

接下来会以我最近刚写的一个小项目 git-master-merged 为例，说一说如何利用 Github 和相关平台的能力实现上面提到的内容，说的很差或者错误的地方欢迎你们指出来。git

简洁的说明

在每个 Github 项目的最上方，都有一小块地方让咱们来填写项目的描述、相关连接和对应的主题。也许是由于地儿过小了，你们没注意，这里都是空白的一片。不过不能由于块头小就小瞧呀，那潘长江还活不活了！悄悄地告诉你们，Github 的搜索功能就是根据这里的描述和主题进行的，因此这里最好能一句话讲清楚项目的功能和做用，从而既能方便别人快速了解，也能让更多人搜索到该项目，例如这样：github

如今愈来愈多的项目喜欢在描述的开头加上一个 emoji 表情，能够参考这份 emoji 列表，将形如 :xxxx: 的短语粘贴便可展现成表情。web

完善的测试

“可靠性”这个词现在被频繁的提起，假如一个开源的项目没有任何测试代码，那么怎么能奢求别人在生产环境中使用呢？各个语言都有不一样的测试框架，如 JavaScript 的 mocha、jest，Python 的 unittest 等，基本用法和概念都类似，这里就不赘述了。这儿主要谈谈**持续集成（Continuous integration，简称CI）**在开源项目中的应用。segmentfault

因为开源项目迭代速度较快，并且常常会收到别人的 pull request，因此如何在快速迭代中，保持较高的质量成为了一个重要的问题。经过持续集成，咱们能够在本身 commit 或者在接收他人 pull request 时，自动触发测试代码的执行，从而能经过测试结果快速、直观地发现错误，让质量获得保障。bash

git-master-merged 项目所使用的持续集成工具是 Travis CI，对于 Github 上的开源项目，能够无偿使用。使用起来也很是简单，一共只有四步：前端框架

用 Github 帐号登陆 https://travis-ci.org/；
选择要使用 Travis CI 的项目：
在项目中添加 .travis.yml，通常在该文件中指定语言和测试环境；
commit 刚刚做出的修改，并推向 Github 仓库。

（更详细的说明能够参考官方文档）

假如一切顺利的话，就能够在 Travis CI 的后台看到经过的结果，从而使用 build: passing 的徽章：

除了测试用例是否经过外，测试代码的覆盖率也是一个很重要的指标。咱们也能够经过持续集成的方式，在 .travis.yml 文件中添加相关字段的说明，从而在 codecov 等网站上自动检测 diamante 覆盖率，从而再领取一枚徽章。

个性化的徽章

看到这些勋章是否是内心就有点痒痒的，想尽快为本身的项目也添加上？这里强烈推荐 http://shields.io/ 这个网址，经过它，咱们能够为项目添加上各类各样的徽章，例如：

项目的最新版本；
项目的被使用状况；
项目的兼容状况；
测试是否经过以及代码覆盖率状况；
代码质量和风格状况。

若是上述这些功能都不能知足你的话，还能够自定义专属于本身的勋章！这里有一篇 GitHub 项目徽章的添加和设置详细介绍的文章，我就很少说了，你们赶快用起来吧 :smile:

规范的提交记录和更新说明

规范的提交记录和更新说明，既可让使用者清楚地知道更新的内容从而有更强的意愿进行升级，也可让项目参与者了解项目的演进历史和当前情况从而更好地进行后续开发。再者，规范的提交记录，能够在出现问题时，快速地定位，找到错误代码，从而解决问题（也能够更快地知道是谁犯了错👻）。

当前社区中使用较多的 commit 提交规范是 Angular 规范，英文文档能够阅读 Git Commit Message Conventions，中文详尽的介绍能够阅读 Commit message 和 Change log 编写指南，这里简要地介绍一下：

commit 的格式包含 Header、Body、Footer 三个部分，形如：

<type>(<scope>): <subject>

<body>

<footer>
复制代码

其中，Header 是必须，Body 和 Footer 能够省略。进一步，Header 中，说明影响范围的 scope 能够省略，可是表示种类的 type 和 subject 必须包含，其中 type 只能从下列 7 中标识选取：

feat：新功能
fix：修补 bug
docs：文档
style：格式化代码
refactor：重构
test：完善测试
chore：其它维护相关更改

人老是不可靠的，有了规范以后，咱们能够经过相关工具来提交和检查提交记录，并自动生成更新说明：

使用 commitizen 来进行交互式的 commit 提交，从而减小不规范的状况；
使用 commitlint 来检查不规范的 commit 提交，从而提出不规范的记录；
使用 conventional-changelog 来自动地根据 commit 中 feat、fix、Performance Improvement 和 Breaking Changes 生成更新说明，并且是增量更新，并不会覆盖已有的文件内容。

这里经过几张图片了解一下：

清晰的模板

对于开源项目而言，他人给项目提 issue 或者 pull request 都是十分频繁的，做为项目的开发者或者维护者，最但愿他人提供的信息是简洁、明了且有用的。经过 github 提供的能力，咱们能够编写一套模板，让他人在使用时直接往其中填入内容便可。整个过程也十分简单：

在项目根目录下建立目录 .github；
编写文件 .github/issue_template.md 文件：

### Expected behavior


### Actual behavior


### Steps to reproduce the behavior
复制代码

变动提交至 github 并观察效果：

官方文档能够参考：

Creating an issue template for your repository

Creating a pull request template for your repository

写在最后

仍是拿谈恋爱举例子吧，“外在决定两我的在一块儿，内在决定两我的在一块儿多久”，一个看起来“高大上”的门面固然能够吸引更多的人来使用咱们的项目，可是只有项目自己具备较高的价值并积极运营时，才能留下用户，让项目更好地运做下去。

但愿开源社区能发展地愈来愈好！

博客原文连接