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

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

本作品采用《CC 协议》,转载必须注明作者和本文链接
《L04 微信小程序从零到发布》
从小程序个人账户申请开始,带你一步步进行开发一个微信小程序,直到提交微信控制台上线发布。
《L03 构架 API 服务器》
你将学到如 RESTFul 设计风格、PostMan 的使用、OAuth 流程,JWT 概念及使用 和 API 开发相关的进阶知识。
讨论数量: 46

然而我还缺一个轮子没造

6年前 评论

然而我还缺一个轮子没造

6年前 评论

而我, 就是那个star你们的人

6年前 评论
Summer

超哥系中国区 PHP Star 数排名第一 --> Php in China | Git Awards
写这个话题当仁不让哈

6年前 评论

感谢分享,看来我要在代码规范和测试上更加努力了

6年前 评论

@lazyou 原来是你!

6年前 评论

厉害了

6年前 评论

超哥的响应速度真不是吹,上次的issue直接秒回。

6年前 评论

这里我想提一下市场的重要性。

jcc 当初的 blog 非常的火,因为正值 vuejs 快速发展之时,与 laravel 的结合也十分顺应了开发者们学习的项目。

我的 vbot 当时只是出于好玩,觉得 python 做出的机器人很酷,然后在 github 上没有发现好的 PHP 微信机器人项目,因此诞生。

总而言之,做一个有市场、有价值的项目,就算有类似的也不怕,只要你觉得自己能做得更好。

6年前 评论
Ryan

学习了

6年前 评论

我想认真的问下 写这篇文章用了多长时间

6年前 评论

为嘛订阅号是装假我会写代码?

6年前 评论

期待下一个话题《基于 Composer 的模块化开发》

6年前 评论

@Calvinsily 难道名称还有啥规定?

6年前 评论

@JokerLinly
@overtrue 然而我有几个小轮子(小玩具) 缺给我star的 童鞋们 star走起 https://github.com/wujunze/nginx-http-echo...
https://github.com/wujunze/panda

6年前 评论

@Hanccc Vbot现在也不错 很?

6年前 评论

@overtrue 不是这个意思,我是说签名档那里是装假我会写代码,不应该是假装我会写代码?

6年前 评论

@overtrue 为了防止你一脸懵逼我特地帮 @Calvinsily 截图

file

6年前 评论

@Hanccc 哇,竟然在第一页了。哈哈,当时很少 Laravel + Vuejs 的结合例子,各种姿势 Google 都是无果。

file

6年前 评论
nickfan

有个开放的心态很重要,另外一点就是你没法满足所有人,也没有义务如此,手工赞一个。

6年前 评论

不过我觉得正如超哥说的,所有的开源需求基本来源于项目,社区的需求。跟着超哥脚步,绝对没有错。:laughing:

6年前 评论

@Calvinsily 哈哈,天啦你说的这个啊,我的锅,sorry!

6年前 评论
godruoyi

就是,以后有啥好的开源项目,都来laravel china at 超哥。

6年前 评论

@Summer 你是不是想让我看到你是number two /斜眼笑

6年前 评论

@DanceSmile 看起来你已经 GET 到点了,哈哈

6年前 评论

@cjjian 所以做第一个吃螃蟹的就对了

6年前 评论
xujiajun

感谢分享。学习了。已加微信,已关注公账号。接下来文档真要好好写了(第一优先级),顺便广告下,tastphp,一个现代化phper用的框架,没有历史包袱。值得一试。还有我其他项目也可以关注下。赶紧Star起来吧!? 地址:https://github.com/tastphp/tastphp

6年前 评论
franktrue

学习了!谢谢

6年前 评论

感谢巨人们的肩膀,让我们少走了很多弯路

6年前 评论

我也来求围观的 这次应该不算轮子~ 一个简单的Emmet-Template-Engine~ 有用的话, 点赞/star:smile:

6年前 评论

拖到最下面,点赞,拖回去,看文章

6年前 评论
xujiajun

@mingyun https://docs.tastphp.com/zh/ 托管在gitbook上,你试下 https://www.gitbook.com/ 能打开吗?

6年前 评论

我知道,你是写七牛那个插件的人,而我,是写支付宝插件的那个人,类库wending/alipay,需要直接通过composer安装,支持支付宝当面付,企业的支付宝可以实现用户花呗支付和其他支付方式。
你是本站站长吗?

6年前 评论

看到最后,来了一句 “本帖由 Summer 于 3年前 取消置顶” 有点尴尬

3年前 评论

考古来了。大佬竟然没考过四级。

2年前 评论

讨论应以学习和精进为目的。请勿发布不友善或者负能量的内容,与人为善,比聪明更重要!