史上更全的开源项目创做指南

前言

开源，是这个时代的主旋律。做为一名Android开发工程师，我有理由相信咱们是开源的最大受益者，由于那个养活咱们的Android其自己就是Google的开源项目。在这样一个开源的时代，就连以前那个最排斥开源的"微软"也不得不积极拥抱开源，大手笔收购github以表本身的开源决心。

前段时间我在逛github的时候，偶然间发现，个人github已经拥有12个star过百的开源项目，2个star过千的项目。回首一想，原来我作开源项目已经快3年了，想一想这一路走下来真的很是不易。

深夜和周末是我作开源项目的主战场，电脑和AndroidStudio是我创做的纸笔，各类bug和issues是我通往卓越项目的拦路虎，常常为了解决一个问题独自思考到凌晨。这其中还要饱受喷子们的挖苦和质疑，以及白嫖党的夺命连环call。固然，也会有人站出来讲几句公道话，可是平心而论，国内的开源环境真的不好。

若是不是由于对技术的热爱以及支持者的鼓励，我相信我很难坚持下去，就像那些渐渐消失的开源项目创做者同样，提交记录永远地停留在了那一刻。

因此，为了可以记录下个人这段艰苦开源之旅，同时也是但愿可以改善国内的开源环境，帮助更多但愿从事开源项目的有志青年，我决定写下这篇开源项目经验总结。

为何作开源项目

在决定作开源项目以前，你很是有必要问一下本身：我到底为何要作开源项目？不管是出于什么目的，只要你有答案的话，那么你就能够继续往下看，不然如下的内容可能对你来讲没有任何意义。

提及开源，就不得不提Google这家极具开源精神的公司。做为一家美国科技公司，每一年都在不断地对外输出着无数优质的开源项目，与此同时，近几年咱们国家的科技公司们也开始着手开源计划，开源了很多有趣的项目。

那么为何大型的科技公司都在积极地作开源项目呢？其实缘由很简单，无非就是为了名气和企业的形象嘛。做为一家市值超百亿的科技公司，不搞点开源项目出来装装逼，都很差意思说本身是大厂。

那么做为咱们我的开发者而言，有必要作开源项目吗？在回答这个问题前，你有必要问一下本身：你真的热爱作技术吗？若是说你作技术的目的只是为了养家糊口的话，我以为接接私活，作作外包比较适合你。由于作开源项目真的是那些"闲得蛋疼"的人打发时间的玩具，在这条道路上你会发现很是没有"钱途"。只有当你真正将技术做为一种兴趣来热爱的时候，你才能体会到那种开源项目被无数人引用后的价值和喜悦感。

因此，说了这么多，咱们究竟为何要作开源项目呢？如下列举个人几点理由，供你们参考：

• 提升本身的技术水平。毕竟开源项目就至关于把本身扒光了给别人看，也许这样比喻不是很恰当，但确实能提升本身代码的质量和解决问题的能力。毕竟若是你的开源项目真的有人用的话，你必然会收到不少的issue以及建议，这些东西可能你以前根本就没有想到。
• 让项目变得更加健壮。开源的最大妙处就在于，任何人都有权利看到你项目的代码，提出本身的建议。这其中就有可能发现项目中存在的漏洞，以及一些很是有建设性的建议，同时也能让你明白本身项目中存在的不足，这样就会推进项目不断的优化升级，项目的质量也会呈螺旋型上升而变得更加健壮。
• 结交志同道合的朋友。你在作开源项目的同时，很容易就能结交到与本身志同道合的开源创做者，毕竟你们都是但愿开源项目越作越好，颇有可能你的开源项目被其余的开源者所赏识而一同开发和维护。这样一来一去大家颇有可能成为"同志"，哈哈。
• 帮助他人，提高本身的行业影响力。这也是不少人作开源的重要目的。若是你有幸可以在某个领域作出一个很是优质的开源项目而且有不少人引用的话，那么你在该领域的名气必定会蹭蹭的往上冒，到那时什么都会有的，具体可参考vue.js的创做者：尤雨溪。
• 展现我的的技术水平。不少人作开源项的目的就是它可以在应聘面试中加分，尤为是应聘某些大厂。由于经过那短短几小时的面试其实并不能很全面地考察出一我的的技术水平，并且面试一般仅仅是两我的面对面空谈几小时，若是这个时候你能拿出一个较为优秀的开源项目的话，必定会加分很多，至少能在面试前给面试官营造一个不错的印象。
• 实现本身的人生价值。开源给予了你无穷大的创做自由，在上面没有产品经理提出的各类脑残需求，也没有测试提出的各类过分测试bug，更没有各类技术条条框框以及企业规范。你能够作任何你认为对或者感兴趣的事情；你能够实现本身儿时改变世界的梦想；你能够留下你在这个世上存在过的印记；你能够...开源给予你无穷大的舞台，你能够作不少有意义的事情，当热前提仍是不能违法法律...触犯法律的事情咱们不能作，毕竟仍是保命要紧，哈哈。
• 收获意想不到的业余收入。虽然开源是免费的，不该以盈利为目的。可是不得不说没有经济效益的驱使，单纯靠对技术的热爱实际上是很难坚持下去的，尤为是当你面对不少现实生活的压力时，情怀就显得那么苍白无力，这也是为何各大开源平台都为开源者提供了赞助和打赏的渠道，毕竟开源者也要赚钱生活。好的开源项目实际上是可以收获至关可观的打赏的，更有甚者能够搞一个商用版，受权使用，赚取服务费等，固然能作到这一步的开源项目仍是很少的。

如何作好开源项目

上面我简单讲述了咱们为何要作开源项目，若是此刻你心中有了答案，那么恭喜你，你已经成为一名准开源创做者，那么下一步咱们就是探讨如何作好一个开源项目。

我作了近3年的开源项目，其中最为成功的 XUI 近600次的代码提交，齐全的文档和视频教程，目前也不过收获了2.7k的star量，因此说作好一个开源项目实际上是很是不易的。

下面我就简单拿 XUI 项目为例，简单介绍一下衡量一个开源项目质量的几项指标。

• 项目的热门程度：项目的star、fork和watch量。
• 项目的活跃度：这里考量的因素包含issue的整体数量、open issue和closed issue的数量、issue回复和解决的速度、pull requests的数量、项目最后一次提交的时间。
• 文档是否齐全：是否有wiki或者README.md。
• 项目的稳定性：代码提交的频率，项目版本发布的频率。
• 项目的潜力：项目开发的分支数、项目的开发计划以及项目参与者的数量等。
• 项目代码的质量：设计是否合理，是否符合设计模式原则，考虑项目的可扩展性、便利性和稳定性。
• 开源做者的水平：做者其余项目的star量和行业影响力。

只有了解了以上指标，咱们才能创做出更加优质的开源项目。那么说了这么多，咱们如何才能作好一个开源项目呢？请继续往下看！

1.选对开源托管平台

开源托管平台以 github 做为首选，码云 做为备份。

虽然目前市面上开源项目的托管平台很是多，好比：码云、码市、gitlab、BitBucket、SourceForge，不过我仍是极力推荐github，毕竟github使用的人群最广，人数最多，谁不想本身幸苦创做的开源项目能被更多人看见呢。虽然github是一家美国企业，往后有被禁掉的风险，可是我相信一个崇尚自由、民主的国家，对禁开源平台这件事情仍是不会那么顺利的，毕竟开源无国界，开源不该政治化，商业化！若是你仍是担忧github往后会被禁，那么很简单，你直接把你的github项目一键导入到码云中做为备份，毕竟码云是获得国家承认的，仍是比较可靠的。

2.好的创意或者理念

若是一项功能、一件事情你们每次都须要重复去作，可是又没有什么好的解决方案或者轮子的话，这个时候咱们就能够尝试去作一个。

一个好的开源项目都是为了解一个问题而诞生的。若是你有好的创意或者理念，那么你就更能吸引更多的人参与到项目的建设中，那样也会有更多的人关注到你的项目，这样你的项目想不火起来都难。

我当初创做 XUI 就是但愿可以简化Android界面开发的难度，提高Android界面开发的效率而作的尝试。相信作过Android的人都知道Android原生组件在国内很不受设计师的待见，至于Google推行的Material Design设计风格更是无人问津，这就致使了设计师给出的原型图几乎是清一色的IOS风格，更尴尬的是，网上Android相关的开源UI库是少之又少，几乎全部的基础组件都须要本身重写。正巧当时我接触到了React和Vue，发现它们都有很是方便的UI库，直接在示例代码的基础上修修改改就能大体上实现本身想要的效果，极大地提升了开发的效率,后来我又借鉴了QMUI 相关的思想，最终创做出了 XUI 这个开源项目。

因此，一个好的创意或者理念对于开源项目来讲很是重要，能够说是开源项目的灵魂。

3.好的设计和代码质量

若是说一个好的创意或者理念是开源项目的灵魂的话，那么一个好的设计和代码质量就是开源项目的骨骼和肉体了。

3.1 掌握设计模式

要想有好的设计，首先你须要很是熟练地掌握设计模式，那么如何才能熟练地掌握设计模式呢？在这里我能够教你们一些经验：

• 1.首先了解设计模式的几大基本原则。这里我有一篇讲关于 设计模式原则的博客 可供你们参考。
• 2.其次初步学习现有的二十几种设计模式，并在平时的工做或者开源项目中尝试使用。这里我有一个专门介绍设计模式使用的开源项目 ,里面有相应的介绍和源码可供你们参考。
• 3.最后等你熟练使用了上面的二十几种设计模式后，忘掉他们，从新回顾以前的设计模式基本原则，并以此做为往后项目设计的基本原则。

其实学习设计模式很是像武侠小说中修练一门武功，学习设计原则是修炼心法、内功，而学习现成设计模式则是修炼招式。只有提高内功，牢记心法，忘记招式才能真正意义上掌握了设计模式这一项技艺。

3.2 严格的代码规范

提升代码质量最简单的途径就是严格遵循通用的代码规范，这里我推荐阿里巴巴Java开发手册 和它的IDE插件p3c项目 。

只有遵循通用的代码规范，这样才更加利于开源项目的多人协做，除非你想一我的维护整个项目，不然你的代码写得那么骚，谁能看得懂？

4.丰富的案例或者测试用例

做为一个合格的开源项目，提供一些单元测试用例仍是很是有必要的，由于你写出来的东西并无专门的人给你测试，这个时候若是尚未相应的单元测试用例，你如何保证你写出来的东西不是个坑呢？

若是你的项目不太适合写单元测试用例的话，那么你最好能提供丰富的使用案例，这样才能让你的开源项目更具吸引力，让别人有东西能够上手实践，不然光秃秃的啥也没有，你写这个项目的意义又在哪里？

5.完善的文档

这里的文档主要包括README（简介）和wiki（使用文档）。下面是文档的几项基本要求：

• 1.文档内容应当尽量的简洁明了，井井有条，而且将其放置于显眼的位置，便于他人寻找。
• 2.文档应当及时更新，避免出现文档与代码不一致的状况。
• 3.提供多语言版本的文档，至少英文版文档是要有的。

5.1 README编写

README可谓是开源项目的门户，每一个人都是从阅读你写的README开始了解你的开源项目的。README写得好与坏，可能直接关系到别人在你的开源项目主页上停留的时间，以及他们是否会给你的项目一个小星星，记住这里很关键！

若是你以前历来都没有写过README，那么这里我推荐一个国外人写的教科书式的项目Standard Readme ,里面写的内容很是经典，能够拿来借鉴。

那么，一个写得好的README应当包含哪些内容呢？如下是我总结出来的经验仅供参考：

• 项目简介（必须）：用几句话简要描述你的项目特色、优点以及项目目标（解决何种问题）。
• 做者简介（选填）：这里是你推广本身或者其余项目的地方。
• 项目背景（选填）：这里能够写你创做该项目的原因和过程。
• 项目特色（必须）：这里是你区别于其余项目的关键，能够写你项目独有的功能、优点、理念等。
• 项目设计（选填）：这里能够阐述项目的设计思想和理念。你能够借助流程图、思惟导图、UML类图、时序图等方式进行阐述。

• 项目演示（必填）：这里是别人能最直观感觉项目魅力的地方。你能够经过如下5种途径进行演示。

  • gif动画演示
  • 视频演示
  • 图片演示
  • 在线演示
  • Demo下载
• 集成/安装指南（必填）：这里你得告诉别人如何才能快速地使用上你的项目。
• 使用文档（必填）：这里你须要告诉别人该如何正确使用你的项目，越详细越好。固然若是内容过多的话，仍是建议直接给一个使用文档首页的连接或者视频教程，这样可能会更友好一点。
• 相关项目（选填）：这里是你推广其余开源项目的地方，是让你的项目粉丝数产生裂变的地方，必定不要错过。
• 如何贡献（选填）：这里的贡献包括两个方面：代码贡献和打赏和赞助。对于代码贡献，你须要写出你的提交规范和行为准则，以免没必要要的麻烦。
• 特别感谢（选填）：这里写上对你项目有过帮助或者启发的人或者项目的地址，以此表达对他们的感谢。
• 联系方式（选填）：这里能够写你为此项目建立的QQ技术交流群、微信公众号等。
• 许可声明（选填）：这里你能够写你项目的开源协议或者许可以使用的范围（好比：禁止用于商业用途，仅供学习）。若是你分免费版或者商用版的话，也能够在这里进行说明。

具体内容你能够参考 XUI项目的README 或者个人README模版 。

5.2 wiki编写

wiki的编写和及时更新很是重要。wiki最好分模块进行编写，作到条理清晰，井井有条，通俗易懂。

下面我就以个人另外一个开源项目XUpdate 的wiki来简单说一下，wiki咱们该如何编写。若是你会在线文档编写的话，这里能够直接跳过。

wiki主要能够分为三块，如上图所示，最上面是项目的简要描述，左侧是文档的首页，右侧是文档的目录。这里我为了偷懒，左侧的文档首页直接照抄了右侧的文档目录。

下面我简单列举咱们的wiki中应当包含哪些内容：

• 简介：虽然这里的简介绝大多数是和README重复的，可是最好仍是不能漏。

  • 项目简介：这里包括项目描述、项目特色、项目背景、项目设计思想等内容。
  • 集成/安装指南：若是你的项目是轮子库，那么就编写集成指南。若是你的项目是完整项目，那么就编写安装指南。
  • 项目演示：gif动画、视频、图片演示，在线演示和demo下载二维码任选几项提供便可。

• 若是使用

  • 基础使用：顾名思义，可以知足最基础需求的使用介绍。
  • 进阶使用：这里主要介绍一些个性化（自定义）、深刻使用的操做。
  • 常见问题：常见问题的整理很是重要，它每每产生于issue或者技术交流群中常见的问题，对刚接触该项目的人很是有用。
• 配套设施：一个优秀的开源项目每每会自建相应的生态，这时配套设施就很是有必要了。

6.合理的版本管理和规划

新版本的发行不宜过于频繁，也不宜间隔时间过长，胡乱无规律的版本发行对使用者而言简直是场灾难。

最恰当的作法应该是：在保证充分测试没有问题以后，按期发布最新版本，实时更新项目的最新进度以及将来的开发计划。

这里我提供几点建议供你们参考：

• 每次在进行新版本的开发时，建议单独拉一个dev版本分支，减小对主分支的影响。

• 可使用github上的projects来规划你的项目开发计划。

• 能够在issues中建一个置顶的issue来收集使用者的反馈，以此做为新版本开发的规划素材。

• 每次新版本发布的时候，必定要提供详细的版本日志，方便使用者参考和追踪。同时，对于几个改动比较大的版本调整必定要有明确的说明，不然使用者会很是疑惑。

7.关注反馈，持续更新

7.1 及时处理issue

issues是使用者与项目开发者之间沟通的桥梁。不少使用者提出的issue仍是很是有建设意义的，及时高效地处理掉它们，可让咱们的项目变得更加完美。

在处理issues的过程当中，咱们能够收集整理"常见问题"，收获好的idea，了解本身项目存在的不足等。这就要求咱们须要及时关注和处理使用者提出的这些issues。

那么咱们怎样才能快速高效地处理issues呢？这里我提供几点建议：

• 1.提供issue模版，过滤无效issue，提高沟通的效率。这里你能够参考 XUI的issue模版 。

• 2.自定义issue标签，对issue作分类管理，部分issue能够优先处理。

7.2 欢迎PR，及时处理PR

在开源项目初期，靠一我的维护一个项目仍是不难的。一旦项目热度上去来，光靠一我的的精力是远远不足以维护整个项目的，这里我深有体会。

因此咱们须要提供PR提交规范和行为准则，积极欢迎更多的人参与到项目的维护中。同时对于别人提出的PR，咱们要及时review验证，对于没有问题的提交应当适时合入以提升别人参与贡献的积极性。

8.作好推广

酒香不怕巷子深，这句名言在互联网时代是行不通的。你就是有再好的创意、再好的设计，若是没作好推广的话，也是没人能看到你的开源项目的。

如何推广本身的开源项目，对此我仍是很是有经验的，下面我就提供几个途径：

• 在各大技术论坛、博客、社区不断地发文章介绍本身的开源项目。我经常使用的几个平台有：CSDN 、掘金 、思否 、简书 、知乎 、哔哩哔哩 。
• 在一些开源项目推荐分享平台上提交本身的项目请求收录。好比个人开源项目XUI 和 XUpdate 提交到了HelloGitHub 上。
• 组建本身的开源社区。你能够建立qq交流群、微信公众号或者社区网址来推广你的项目。
• 加入知名的组织。好比我就加入了B3log 开源社区 。

9.不忘初心，摆正心态

作开源项目是一件很是漫长的过程，你可能根本想象不到前方的道路有多么的曲折。

假如你的开源项目作了几个月了也无人问津，不要气馁，专心去作你认为有价值的事情便可，总有一天会有人发现你项目的价值。

假如你的开源项目作成功了，在收获到很多人赞扬的同时，那么势必会遭到不少喷子们的冷嘲热讽以及各类无脑喷。不要理会那些只会喷可是啥也不会作的麻瓜，不要把你有限的精力放在这些人身上。请把你有限的精力放在那些给你开源项目提出宝贵建议的人身上，专心去作你认为对的事情。

最后

我花了整整一周的时间整理才写下了这篇文章，也是真诚地但愿可以改善国内的开源环境，帮助更多但愿从事开源项目的有志青年。若是你以为有用的话，建议你收藏此文章。最后，仍是祝愿你们能早日写出属于本身的优秀的开源项目！！！

微信公众号

更多资讯内容，欢迎扫描关注个人我的微信公众号:【个人Android开源之旅】