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

淩亂°似流年 2022-12-23 11:24 158阅读 0赞

## 前言 ##

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

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

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

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

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

## 为什么做开源项目 ##

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

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

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

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

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

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

## 如何做好开源项目 ##

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

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

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

![open\_project.png][open_project.png]

*  项目的热门程度：项目的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.首先了解设计模式的几大基本原则。这里我有一篇讲关于 [设计模式原则的博客][Link 1] 可供大家参考。
 *  2.其次初步学习现有的二十几种设计模式，并在平时的工作或者开源项目中尝试使用。这里我有一个专门介绍[设计模式使用的开源项目][Link 2] ,里面有相应的介绍和源码可供大家参考。
 *  3.最后等你熟练使用了上面的二十几种设计模式后，忘掉他们，重新回顾之前的设计模式基本原则，并以此作为日后项目设计的基本原则。

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

#### 3.2 严格的代码规范 ####

提高代码质量最简单的途径就是严格遵循通用的代码规范，这里我推荐[阿里巴巴Java开发手册][Java] 和它的IDE插件[p3c项目][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][XUI_README] 或者我的[README模版][README] 。

#### 5.2 wiki编写 ####

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

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

![wiki\_example.png][wiki_example.png]

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

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

*  简介：虽然这里的简介绝大多数是和README重复的，但是最好还是不能漏。
    
     *  项目简介：这里包括项目描述、项目特点、项目背景、项目设计思想等内容。
     *  集成/安装指南：如果你的项目是轮子库，那么就编写集成指南。如果你的项目是完整项目，那么就编写安装指南。
     *  项目演示：gif动画、视频、图片演示，在线演示和demo下载二维码任选几项提供即可。
 *  如果使用
    
     *  基础使用：顾名思义，能够满足最基础需求的使用介绍。
     *  进阶使用：这里主要介绍一些个性化（自定义）、深入使用的操作。
     *  常见问题：常见问题的整理非常重要，它往往产生于issue或者技术交流群中常见的问题，对刚接触该项目的人非常有用。
 *  配套设施：一个优秀的开源项目往往会自建相应的生态，这时配套设施就非常有必要了。

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

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

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

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

*  每次在进行新版本的开发时，建议单独拉一个dev版本分支，减少对主分支的影响。  
    ![3835bd35f85eb59f0dcd53937877fcb0.png][]
 *  可以使用github上的projects来规划你的项目开发计划。  
    ![c8679d4d5c87cda5a9acbf57c6a57222.png][]
 *  可以在issues中建一个置顶的issue来收集使用者的反馈，以此作为新版本开发的规划素材。  
    ![07a2c0b0295b8329bcf527574d04e5d5.png][]
 *  每次新版本发布的时候，一定要提供详细的版本日志，方便使用者参考和追踪。同时，对于几个改动比较大的版本调整一定要有明确的说明，否则使用者会非常疑惑。  
    ![d00ebc35f3367acc14c49d9f6726cad5.png][]

### 7.关注反馈，持续更新 ###

#### 7.1 及时处理issue ####

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

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

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

*  1.提供issue模版，过滤无效issue，提升沟通的效率。这里你可以参考 [XUI的issue模版][XUI_issue] 。

![issues\_template.png][issues_template.png]

*  2.自定义issue标签，对issue做分类管理，部分issue可以优先处理。

![issue\_labels.png][issue_labels.png]

#### 7.2 欢迎PR，及时处理PR ####

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

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

### 8.做好推广 ###

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

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

*  在各大技术论坛、博客、社区不断地发文章介绍自己的开源项目。我常用的几个平台有：[CSDN][] 、[掘金][Link 3] 、[思否][Link 4] 、[简书][Link 5] 、[知乎][Link 6] 、[哔哩哔哩][Link 7] 。
 *  在一些开源项目推荐分享平台上提交自己的项目请求收录。比如我的开源项目[XUI][] 和 [XUpdate][XUpdate 1] 提交到了[HelloGitHub][] 上。
 *  组建自己的开源社区。你可以创建qq交流群、微信公众号或者社区网址来推广你的项目。
 *  加入知名的组织。比如我就加入了[B3log 开源社区][B3log] 。

### 9.不忘初心，摆正心态 ###

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

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

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

## 最后 ##

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

## 微信公众号 ##

更多资讯内容，欢迎搜索我的微信公众号:【我的Android开源之旅】

[github_xuexiangjys.png]: /images/20221120/8a4ea1d9dfa24ccba1ef239e9fdc95bc.png
[XUI]: https://github.com/xuexiangjys/XUI
[open_project.png]: https://img-blog.csdnimg.cn/img_convert/588165f44ee462e9b46119aafb3fdc25.png
[github]: https://github.com/
[QMUI]: https://github.com/Tencent/QMUI_Android
[Link 1]: https://xuexiangjys.blog.csdn.net/article/details/78924201
[Link 2]: https://github.com/xuexiangjys/architect-java/tree/master/src/designpattern
[Java]: https://github.com/alibaba/p3c/blob/master/Java%E5%BC%80%E5%8F%91%E6%89%8B%E5%86%8C%EF%BC%88%E5%B5%A9%E5%B1%B1%E7%89%88%EF%BC%89.pdf
[p3c]: https://github.com/alibaba/p3c
[Standard Readme]: https://github.com/RichardLitt/standard-readme
[XUI_README]: https://github.com/xuexiangjys/XUI/blob/master/README.md
[README]: https://github.com/xuexiangjys/AndroidAdvancedLearning/blob/master/Chatting/XREADME.md
[XUpdate]: https://github.com/xuexiangjys/XUpdate/wiki
[wiki_example.png]: https://img-blog.csdnimg.cn/img_convert/cc75e40a56ab71ba460aa815d2ad3c37.png
[3835bd35f85eb59f0dcd53937877fcb0.png]: https://img-blog.csdnimg.cn/img_convert/3835bd35f85eb59f0dcd53937877fcb0.png
[c8679d4d5c87cda5a9acbf57c6a57222.png]: https://img-blog.csdnimg.cn/img_convert/c8679d4d5c87cda5a9acbf57c6a57222.png
[07a2c0b0295b8329bcf527574d04e5d5.png]: https://img-blog.csdnimg.cn/img_convert/07a2c0b0295b8329bcf527574d04e5d5.png
[d00ebc35f3367acc14c49d9f6726cad5.png]: https://img-blog.csdnimg.cn/img_convert/d00ebc35f3367acc14c49d9f6726cad5.png
[XUI_issue]: https://github.com/xuexiangjys/XUI/blob/master/.github/ISSUE_TEMPLATE/bug_report.md
[issues_template.png]: https://img-blog.csdnimg.cn/img_convert/c0f3bced8ce08bb0c7c74d13ceef3c90.png
[issue_labels.png]: https://img-blog.csdnimg.cn/img_convert/7120a4076a335f34830773714a3a29ff.png
[CSDN]: https://blog.csdn.net/
[Link 3]: https://juejin.im/
[Link 4]: https://segmentfault.com/
[Link 5]: https://www.jianshu.com/
[Link 6]: https://www.zhihu.com/
[Link 7]: https://www.bilibili.com/
[XUpdate 1]: https://github.com/xuexiangjys/XUpdate
[HelloGitHub]: https://github.com/521xueweihan/HelloGitHub
[B3log]: https://github.com/b3log