手把手教你如何构建一个优秀的开源项目

file
这其实是之前在北京 Laravel Meetup 的一次分享内容,不过考虑到有很多人在公众号想听听关于我是如何做开源这个话题,所以就再次拿它讲一个文字版。

file

关于我,这个就没啥可讲的了,EasyWeChat 作者、Laravel China 创始人之一。

file

要想做好开源,这 8 个步骤缺一不可,当然这个过程周期是持续的,你会在不断开源过程中提升自己,学到新的东西。

file

第一件头疼的事情当然是 “做什么?”,不过根据我的个人经验来看,找一个开源项目 idea 并没有想象的那么难,一般有以下三个渠道:

第一个渠道是项目,因为大部分都是来自工作生活中,所以上图我把“项目”排到第一位。很多时候在我们的开发工作中,会经常遇到重复性的工作,比如你每启动一个项目都要搞一遍短信的发送,又得去找一遍用哪家的服务,还得折腾一遍权限系统,其实这些都是激发你创意的好时机。你会发现不是你一个人在重复,而是大家都在这样不停的重复做很多原本不需要重复做的事情。所以这时候就是你造轮子的好时机。

第二个创意来源就是交流群,我相信大部分同学的 QQ 都有不少技术交流群吧,你会发现很多人在群里会提重复的问题,或者一些伸手党会经常来问一些“有没有基于xxx的项目啊”、“有没有人会xxx” 诸如此类的问题。如果你发现这个需求确实挺多的,并且也没有一个好用的轮子,你就动手吧!

第三就是社区,一些论坛或者博客,也是发现需求的地方,基本都是从别人的讨论中发现创意,这些用户就是你的项目最直接用户。

file

做开源项目其实是一件比较费时费心的工作,它的最大难点并不在于代码,而是后期的维护持续的跟进。但是要想制作出一个受欢迎的开源项目,写好代码永远是关键的点,试想一下,一个人从你各种吹 B 的链接点到 GitHub,看到源码乱七八糟,格式不统一,驼峰+下划线各种混写,对齐也是 tab + space,注释基本为 0 的时候那个场景,是很吓人的,所以不管你的抽象能力怎么样,也不管你这个模块写得是否是那么的科学,请做好第一步:写好代码。

上图我列举了一些名词,难免有同学不认识,我这里大概介绍一下:

PSR 是国际框架组织 PHP-FIG(PHP Framework Interop Group) 制定的一系列规范,包括不限于自动加载,编码规范、缓存以及其它一系列接口规范。它虽然不是 PHP 官方标准,但是目前大多数开源项目都是按这个标准来的,所以,有必要认真了解一下。

  • PHPCS 是 PHP Code Sniffer,一款代码规范检查工具,可以根据你的设置来检查代码规范性问题。
  • PHPCBF 是 PHPCS 内置的代码规范修复工具,大部分的代码规范问题它都可以自动修掉。
  • PHPMD 是代码复杂度检测工具,能够很方便的检查你的代码是不是写得复杂度过高。
  • StyleCI 是一款在线的代码规范检查服务,最初的版本是开源的,后来闭源了,核心是基于 PHPCS 来完成。我的所有 PHP 开源项目基本都开通了这个服务来自动检查。
  • Scrutinizer 同样是一款在线服务,不过它的功能比较强大,主要用于检查代码质量问题,比如潜在的 bug,未使用的变量,错误的类型约束,或者重复的代码等,总之是一款很棒的工具。
  • Travis-CI 是一款在线持续集成服务,自动化执行单元测试,或者部署任务等。

GitHub 上有很多类似的服务,你可以查看上面的链接来了解它们,它们都是对开源项目免费使用的。

file

代码写好了别着急直接放到网上,做好了上面第二步我们提到的各种规范检查外,充分的测试也是一个必要的工作。

一般的做法是写单元测试,如果你还对单元测试这个东西不够熟悉的话,是时候发起一波学习了。

在保证足够覆盖度的前提下,结合第二步提到的持续集成服务,这个项目差不多就是可以打 80 分了。

单元测试不仅能保证代码的可靠程度,同时在写测试过程中你会发现你代码设计得不好的地方,我一直使用的一个评判标准就是:编写单元测试的难度与代码质量成反比。

写完测试可以把代码先提交了,但是不要忘记还有一个非常重要的事情没做:写文档。

file

友好的文档是你项目能否吸引别人目光的首要的判断标准。文档都看不明白是个啥根本不可能有人敢用嘛。所以,在推广前,我们第一件事情就是完善文档。如果你的项目不限于国内使用,那最好提供两个版本,或者起码提供英文版本的文档。有一些项目国外是没法用的,比如我最近的轮子 overtrue/easy-sms,它是基于国内的短信运营商的,就算国外能用估计也没有人用,所以这种场景下就写中文说明就够。

一说到写英文,好多朋友第一句就会说:我英文很差啊。其实不要怕出错,大胆去做就好,错了再改。我一个四级都没过的人不也一样写吗,用好各种工具就可以。

如果项目比较小,一般 README.md 就够,如果项目比较复杂,写在 README 感觉太长,可以考虑以下三种方案:

第一种,最便捷的方案就是直接在项目里放一个 docs 文件夹,使用 Markdown 分文件写文档。

第二种,使用 GitHub 官方提供的 Pages 服务建立一个站点,这个具体使用可以去了解一下官方指南。

第三种,就是最复杂的方案,自建网站,这种适用于中大型项目。

那么,文档应该怎么写呢?请你一定要关注以下这些必要的点。

file
file

文档写好了,我们应该发布我们的版本,具体关于如何把 GitHub 项目提交到 packagist 我就不细讲了,这个网上实在是太多讲它的,如果你还是没找到,就去 Laravel China 找到作者 Ryan 的文章《Laravel Composer Package 开发简明教程》

file

发布版本并不是那么随便的一件事情,错误的版本发布将会给用户带来灾难性的问题。

正确的 release 的前提是弄清楚语义化版本(Semantic Versioning),它包含 3 个部分:

主版本号:当你做了不兼容的 API 修改,
次版本号:当你做了向下兼容的功能性新增,
修订号:当你做了向下兼容的问题修正。
所以,请根据你的修改正确的使用版本号。

语义化版本的更多可以去官网(有中文支持)了解。

接下来的事情就是推广,我的一句总结如下:

file

让真正需要它的或者可能需要它的都知道它的存在,这其中有三个核心:

  1. 真正需要它的:这些人已经有这个需求,但是还没解决或者没有很好的解决。
  2. 可能需要它的:正在启动项目或者将要在项目中用到的一类人。
  3. 知道它的存在:你需要正确的引导到你的项目而不是吹了一大堆后来连个链接都不给。

一些在推广过程中更细节的点:

file

你需要有自己的品牌,一个易识别的 GitHub ID、微博账号、微信号等。

在推广过程中你会遇到不少喷子或者闲得蛋疼我就是要骂你两句才舒服的人(根据经验这类人异常的多,知乎尤甚)。不要和他们喷,切记!

另外就是选对目标,不要跑去什么妈妈群或者什么老年人健康中心去推广你的项目,他们不需要。去 Laravel China 吧,这里有一群搞 PHP 的小伙伴(当然还搞其它我就不说了)。

然后选择一个正确的时间点,图里我已经列举,这些时间点大家相对比较活跃,周末都约妹去了你就别浪费时间了。

然后一定要准确并富有表现力的表达,你写的帖子就一行我反正肯定不看的。

然后你需要有一定的反馈渠道,小项目的话 GitHub issue 就足够,大项目你搞个 Q 群,论坛都可以。

file

那有了反馈就要关注,每天抽点时间来看看 issue,分类并加入到改进计划。

请注意,这是最耗时的工作,所以不要影响到你的工作,如果感觉时间已经安排不过来,就找小伙伴一起维护。

如果这个问题很小,那就立即响应修掉再说,比较复杂,就安排到周末,把约妹的时间挤挤。

file

很多时候决定是否要使用你这个项目判断,除了前面提到的文档与代码外,还有以下条件的:最近提交、issue 堆积量。

所以,一个项目的更新活跃度,也是比较重要的。保持项目更新,别人才敢用,不然刚用几天就进你的坑,结果你半月不给人处理,那人家只能弃坑喷人带着愤怒离去。

说了这么多,其实无非就那么8个步骤,每一步都走稳了,你的项目不会差到哪里去。

以下是题外话:

最近在做 EasyWeChat 4.0 的开发工作,我希望是月底能 release,如果没有完成的话你们也不要怪我,因为创业阶段事情比较多。

昨天在 overtrue/laravel-wechat 上一个朋友因为没有细看 README 的说明踩坑了,另外一个热心网友就去提示他,结果他就喷人家,各种骂,实在惨不忍睹,我后来去看了这哥们的博客,他自己不认真所致,这位热心网友并没有与他争吵,这里得点赞,我去解释了一下,结果提问的哥们又来骂我了。做开源心态很重要,这种情商低的朋友很多,不要跟他们吵,你要想一下,你做为一个能写开源项目的人,怎么能跟这种 loser 喷子骂呢是不是,那么多人围观呢,可丢人了。

对了,下一个话题是《基于 Composer 的模块化开发》,敬请期待。

还在等什么,快去公众号 “假装我会写代码” 转发到朋友圈。

file
file