史上最全的开源项目创作指南

本贴最后更新于 379 天前,其中的信息可能已经时异事殊

前言

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

前段时间我在逛 github 的时候,偶然间发现,我的 github 已经拥有 12 个 star 过百的开源项目,2 个 star 过千的项目。回首一想,原来我做开源项目已经快 3 年了,想想这一路走下来真的非常不易。
github_xuexiangjys.png

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

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

所以,为了能够记录下我的这段艰苦开源之旅,同时也是希望能够改善国内的开源环境,帮助更多希望从事开源项目的有志青年,我决定写下这篇开源项目经验总结。

为什么做开源项目

在决定做开源项目之前,你非常有必要问一下自己:我到底为什么要做开源项目?无论是出于什么目的,只要你有答案的话,那么你就可以继续往下看,否则以下的内容可能对你来说没有任何意义。

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

那么为什么大型的科技公司都在积极地做开源项目呢?其实原因很简单,无非就是为了名气和企业的形象嘛。作为一家市值超百亿的科技公司,不搞点开源项目出来装装逼,都不好意思说自己是大厂。

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

所以,说了这么多,我们究竟为什么要做开源项目呢?以下列举我的几点理由,供大家参考:

如何做好开源项目

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

我做了近 3 年的开源项目,其中最为成功的 XUI 近 600 次的代码提交,齐全的文档和视频教程,目前也不过收获了 2.7k 的 star 量,所以说做好一个开源项目其实是非常不易的。

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

open_project.png

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

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 掌握设计模式

要想有好的设计,首先你需要非常熟练地掌握 设计模式,那么如何才能熟练地掌握 设计模式 呢?在这里我可以教大家一些经验:

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

3.2 严格的代码规范

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

只有遵循通用的代码规范,这样才更加利于开源项目的多人协作,除非你想一个人维护整个项目,否则你的代码写得那么骚,谁能看得懂?

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

作为一个合格的开源项目,提供一些单元测试用例还是非常有必要的,因为你写出来的东西并没有专门的人给你测试,这个时候如果还没有相应的单元测试用例,你如何保证你写出来的东西不是个坑呢?

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

5.完善的文档

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

5.1 README 编写

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

如果你之前从来都没有写过 README,那么这里我推荐一个国外人写的教科书式的项目 Standard Readme ,里面写的内容非常经典,可以拿来借鉴。

那么,一个写得好的 README 应当包含哪些内容呢?以下是我总结出来的经验仅供参考:

具体内容你可以参考 XUI 项目的 README 或者我的 README 模版

5.2 wiki 编写

wiki 的编写和及时更新非常重要。wiki 最好分模块进行编写,做到条理清晰,层次分明,通俗易懂。

下面我就以我的另一个开源项目 XUpdate 的 wiki 来简单说一下,wiki 我们该如何编写。如果你会在线文档编写的话,这里可以直接跳过。

wiki_example.png

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

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

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

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

最恰当的做法应该是:在保证充分测试没有问题之后,定期发布最新版本,实时更新项目的最新进度以及未来的开发计划。

这里我提供几点建议供大家参考:

7.关注反馈,持续更新

7.1 及时处理 issue

issues 是使用者与项目开发者之间沟通的桥梁。很多使用者提出的 issue 还是非常有建设意义的,及时高效地处理掉它们,可以让我们的项目变得更加完美。

在处理 issues 的过程中,我们可以收集整理"常见问题",收获好的 idea,了解自己项目存在的不足等。这就要求我们需要及时关注和处理使用者提出的这些 issues。

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

issues_template.png

issue_labels.png

7.2 欢迎 PR,及时处理 PR

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

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

8.做好推广

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

如何推广自己的开源项目,对此我还是非常有经验的,下面我就提供几个途径:

9.不忘初心,摆正心态

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

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

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

最后

我花了整整一周的时间整理才写下了这篇文章,也是真诚地希望能够改善国内的开源环境,帮助更多希望从事开源项目的有志青年。如果你觉得有用的话,建议你收藏此文章。最后,还是祝愿大家能早日写出属于自己的优秀的开源项目!!!

微信公众号

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

  • 开源

    Open Source, Open Mind, Open Sight, Open Future!

    353 引用 • 3283 回帖 • 395 关注
  • GitHub

    GitHub 于 2008 年上线,目前,除了 Git 代码仓库托管及基本的 Web 管理界面以外,还提供了订阅、讨论组、文本渲染、在线文件编辑器、协作图谱(报表)、代码片段分享(Gist)等功能。正因为这些功能所提供的便利,又经过长期的积累,GitHub 的用户活跃度很高,在开源世界里享有深远的声望,并形成了社交化编程文化(Social Coding)。

    193 引用 • 1974 回帖
  • 经验
    24 引用 • 144 回帖

欢迎来到这里!

我们正在构建一个小众社区,大家在这里相互信任,以平等 • 自由 • 奔放的价值观进行分享交流。最终,希望大家能够找到与自己志同道合的伙伴,共同成长。

注册 关于
请输入回帖内容 ...
请输入回帖内容 ...