大家好,我是双越老师,也是 wangEditor 作者。
今年我致力于开发一个 Node 全栈 AIGC 知识库项目 划水AI ,包括 AI 写作、多人协同编辑。复杂业务,真实上线,大家可以去注册试用。
本文我要和大家讨论,一个正式的开源项目,包含哪些特点?我们在评价一个开源项目时,会看哪些关键信息。
背景
近期我在 1v1 评审简历的时候,看到有些同学在简历上写自己的开源项目,并贴上了 GitHub 链接。
简历上写博客地址、开源项目地址,这本身是一个好事儿,也是个人的技术亮点。但也有可能起到反作用 —— 无内容,或无有质量的内容。
例如,自己的博客里就近期临时抱佛脚写了几篇文章,或者都是很早之前写的,没有什么内容和深度。
再例如,帖一个 GitHub 链接,但是就几个 commits ,几个 stars (甚至 0 star),README 也都是脚手架自带的……
但凡遇到这种情况,我都会建议删掉,这并不是加分项,反而有副作用。技术人员就是这样,一分付出就有一分收益,尤其开源项目,记录都是开源的,明白人一眼就能看出来。
开源项目,看哪些方面?
谈到开源项目,大家可能首先第一想到的可能是 GitHub Stars ,甚至之前听说有人卖增加 Stars 的服务,忘了多少钱一个。
GitHub Stars 当然很重要,优秀的开源项目都有很多人关注,有 Stars 。但也有很多其他方面配合,软件是一个整体,光有 Stars 没有其他方面是能一眼看出来的。
下面这些方面,有些是必须的,有些是做到一定程度才能有的,所以大家作为参考,不用要求自己的项目非得有全部的方面。
README.md
README.md 就是你项目根目录里的 README.md
文件,例如 wangEditor GitHub 主页 github.com/wangeditor-…
REAMD.md 是这个项目的简单介绍,是用户看到这个项目的第一眼。正式的项目都会写好 README ,甚至我有些 demo 都会写 README 来记录一些核心的开发步骤,例如下面这个
而有些同学的项目 REAMD 直接没有修改,甚至直接就是 vue 或 react cli 默认的 README ,这也太不正式了。每当看到这种情况,我基本会对这个项目“判死刑”。
Git Commits
一个正式的项目,持续维护的项目,应该一定数量的,合理频率的 commit 提交记录。
像我现在开发的 划水AI 项目,目前有 399 commits ,最近一条是昨天提交的。
如果 commits 数量不多,只有几十条甚至几条,那说明没有持续维护,可能项目比较简单。
如果最近 commits 太久远,几个月之前甚至 1 年之前,说明项目很久没维护了,可能放弃了。
GitHub Stars
Githuh Stars 这个大家最熟悉了,它体现了这个项目的流行程度,例如 wangEditor 目前有 17.5K Stars 和 3.3K Forks
当然,wangEditor 持续做了很多年才积累了这么多 Stars ,你的项目可能没有这么多,没关系,慢慢积累。
如果你能有 100+ stars 这就已经算是一个起步了,如果能有几百个 stars 这就算是很厉害了。
其实获取前 100 stars 并不是难事儿,你只要找准一个功能领域,作出一个开源项目,持续贡献、宣传几个月到半年,大概就能有 100 stars 。
坚持,其实很简单,让自己像傻子一样做就好了。
NPM 下载量
NPM 下载量非常重要,这是真伪鉴别器。
有些项目,尤其是某些网红做的项目,在社区闹的挺欢,GitHub 积累的 stars 也挺多,但一打开 NPM 发现:几乎没人用。
所以,当你选择实用的项目,一定要看看 NPM 下载量,是否有很多人在使用。例如 wangEditor NPM 主页的下载量 www.npmjs.com/package/@wa…
你自己的开源项目,也要在 README 或文档中写清楚如何下载,并引导用户 npm 下载。
Issues
软件最终是给人用的,只要有人用就会有 bug ,或遇到各种使用问题。就会提交 GitHub Issues。
软件不怕有问题,就怕没问题。没问题说明根本没人用。这个世界上只有两种软件:1. 有 bug 的软件;2. 没人用的软件。
所以,一个实用的开源项目一定会有大量的 issues 记录和讨论,例如 wangEditor 的 GitHub issues
你的开源项目,你要在 README 或文档中写清楚,有问题要来提交 issue ,你也要积极回复 issue ,这样慢慢积累多了,就显得很正式。
Git 分支
如果一个开源项目只有一个 main
分支,或少数几个分支,那它一定不是什么正式项目,或项目过于简单。
正式项目会有各种功能开发、优化、bug 修复,一般每个工作都会拉一个新分支,所以会有很多分支。
例如我开发的 划水AI 项目,现在已经有 42 个分支,后面肯定会更多。
GitHub Pull Request
开源项目的最大好处就是,可以让全世界所有的使用者都提交代码,一种代码共chan主义。
所以,一个流行的开源项目一定会有很多 Pull Request ,即别人提交的代码。当然了,也不是每个人都能合并,这看具体情况。
Github Actions
GitHub Action 是一个非常好用的前端工程化 CI/CD 工具,它可以监听分支、PR 等时间,执行你自定义的任务,而且免费。
如果你用 GitHub 托管代码,一般会使用 GitHub Action 来自动化打包、测试、发布等。例如 划水AI 项目的一些发布任务。
如果你没有用 GitHub Actions ,那你仅仅是把 GitHub 作为一个代码托管工具,你代码的产出往哪里发布呢?或者你代码有没有自动化测试?我不得而知。
Github Contributors
开源项目一般会有一个核心维护者,即作者,但最好也能招募一些志同道合的人一起开发。例如 划水AI 现在已经有多人参与开发。
文档和官网
如果你的项目功能没那么复杂,且 README 写的很仔细,那你不需要官网和文档,一个 GitHub 链接就够了。
但如果你项目比较复杂,那就得单独做一个文档来介绍,例如 wangEditor 文档 www.wangeditor.com/v5/getting-…
如果你不想自己购买域名,你可以使用 GitHub Pages 免费搭建一个网站,然后用 VuePress 等工具写文档。
正式的文档,对应正式的项目。文档都没有,甚至没有 README ,项目代码再好也不会有人看。
总结
本文讨论关于开源项目的几个特点,以我多年 wangEditor 开源项目的经验,希望能帮助大家更加全面的认识一个开源项目。
如果你想从 0 开发一个 Node 全栈、复杂、真实上线的项目,可参考我的 划水AI,你可以做出一模一样的。
共勉~