保姆级指南，从0到1打造你的个人开源项目

前言

各位很久不见，有些小同伴大概知道大概1年多以前我开始维护log-record项目（Java业务操作日志记载框架）。这期间项目陆陆续续更新迭代、发布新版本，一起走来也踩了不少坑。这篇文章告急是想给渴望开始写开源项目的同学们一些开源项目维护的实操建议，也算是给本身梳理一下做一个开源项目必要注意的事项。
此外，本文讨论的个人开源项目仅限于代码为主的项目。像一些新闻、教程、电子书、工具集锦类开源堆栈，不在本文的讨论范围内。
固然了，如果你已经是一个经验丰富的开源项目maintainer，那么请赶紧关掉这篇文章，并且接洽我，让我好好抱大腿 ：）
确定项目的主题和方向

起首，我们要重点探讨如何准备个人开源项目。一个最底子的思考是，你的项目灵感从哪里来？当你觉得有了好的想法后，又应该做哪些事前调研工作？
积累灵感

积累灵感是开始一个开源项目的第一步。
很多时候灵感源自于我们日常的学习和技能工作上的积累。例如，在工作中遇到的标题，想办理的BUG，或者对某项技能的深入研究，它们都大概给你灵感。
此外，每天多多阅读技能文章、关注技能新闻以及浏览Github Trending都是获取灵感的好办法，多元化地获取信息对于积累灵感很告急。
做好事前调研，非必要，不造新轮子

之前硕士期间写论文经验的告诉我，当你对一个研究方向没有相识全面的时候，你的大多数想法是很幼稚的，有很大大概已经有前人替你踩过了坑，或者有了现成的框架和产品。
所以在确定你的项目主题之前，一定要充分的进行调研和搜索，保证你的项目在某个方面具有独特性。在调研过程中，你最好要摆列出现有和你相似的产品为何不能满足你的诉求，而你的项目又和他们有哪些差别化的特色。
固然，凡事都不要走两个极端，当你发现你的想法真的非常独特，没有人做的时候，你要考虑下是否是因为本钱过大，或者受众过小的缘故原由，才导致没有现成的产品，那么你来做第一个吃螃蟹的人，会面临的工作量和难度，你本身是否心中有数。
如果在经过认真的调研后，你发现你的想法确实在网络上没有很好的产品，那么它可以作为一个好的发力点。
一步步维护好你的作品

OK，当你有了灵感，并且对于本身的这个想法十分有信心之后，让我们来讨论一下，当你准备正式开始一个项目时，你应该遵循的一些方法和我个人的经验。
对于一个开源项目，华丽的外表并非贬义。你大概必要花大量的工作去做编码以外的工作。此外，你还必要一些推广你开源项目的本领，毕竟，如果一个项目不停不被人瞥见，你也会很快失去动力。但是，不要害怕，有一个好的、有效的灵感实在已经乐成了一半，让我们从拙劣的模仿开始，慢慢成为大师。
能者摹形，大师窃意。
先入为主，写好README

很多时候我们点开开源项目主页，起首就会大抵浏览下项目的README，所以无论如何也要把第一印象做好。
网上有很多关于如何写开源项目README的文章，这里就不睁开讲了，推荐一篇写的还不错的外网翻译：如何写出优雅且有意义的 README
对于我来说，有个很喜欢做的事就是贴上很多小徽章，用户会先入为主的觉得你的项目，有点“专业”。下面用几个堆栈的截图举例子。

我的log-record也像上面的着名堆栈一样，依葫芦画瓢，贴上了几个我认为告急的徽章(Badge)

对于不同类型，不同语言的开源项目，README的写法也千变万化，我也没法给大家推导出一个万能公式，但是我可以给大家介绍几类典型的README：

• spring-boot: 经典Java框架，这种类似的开源项目由于其庞大的生态体系，其README告急是介绍其概念，随后给用户指引到各种外部文档链接。同类型的另有：langchain，hutool等。
  
• transmittable-thread-local: 框架类项目的中文README写法完全可以参考它，Java用户熟悉的跨线程ThreadLocal传递框架，同类型的另有：我本身的log-record等
  
• uptime-kuma: 工具类项目，用于监控各类服务状态，其README基本就遵循了上文章提到的如何写好工具项目README的方法，有LIVEDEMO，有徽章，有编译、安装方式，并且提供了详细文档的跳转。
  
• ChatGLM-6B：另有一些带学术性质的项目，比如很多大模型项目，其README会包罗一些论文引用以及论文数据的复现方式等，同类型的另有：llama3
  

请多多参考良好项目的README，将应有的模块尽量补全，之后慢慢迭代。
尽量清晰的项目结构

除了README，清晰的目录结构也很能吸引用户，以hutool和我的log-record为例，由于是Maven项目，可以尽量让用户可以或许看出module区分。此外，会有一些额外的文件夹，例如：

• .github: Github Action相干
  
• .gitee：Gitee Action相干
  
• docs: 文档聚集
  
• bin: 可执行脚本
  
• LICENSE：开源证书
  
• 等等。
  

比如hutool项目：

log-record项目则是按照Maven模块进行了简单划分：

良好的Git Commit

一个良好的commit记载可以或许让使用者对项目更有信心，也更有说服力，证明其contributor都是（至少表面上是）对代码质量有寻求的开辟者。
我的Log-record，做的不好的是我中英文稠浊。如果你的堆栈明确面向中文互联网，你可以全部以中文来写，但是如果想面对全球用户，还是尽量接纳全英文为上策。

相反，一个差的commit log让人第一感觉就是不专业。这一点要吐槽下hutool

做好版本管理

如果你做的是Java项目，那么最好项目可以或许索引到公共Maven堆栈中，才气吸引更多用户，毕竟用户最必要的是方便地拉取你的包，而不是手动下载上传到用户的私有堆栈里。实在大部分个人的Maven项目都可以提交到公共Maven堆栈中，可以参考之前我的文章：如何提交本身的项目到Maven公共堆栈
以我的log-record项目为例，我会按照下面的顺序，进行版本迭代：

• 开辟新版本代码
  
• 发行SNAPSHOT版，上传至公共Maven堆栈
  
• 打Tag，发行RELEASE版，上传至公共Maven堆栈
  

发行RELEASE版后，你的堆栈主页上会有最新的版本信息，方便用户查看和使用。

https://central.sonatype.com/artifact/cn.monitor4all/log-record-starter

极为告急的测试工作

这一点渴望大家尤其重视，开源项目，也要尽量对用户负责，对项目的质量有寻求，所以做好项目的单元测试和其他集成测试等工作，并且最好可以或许将你的测试覆盖率展示出来，也可以或许增强使用者的信心。
这里推荐一个网站codecov，它可以或许通过多种方式帮你的堆栈维护一个测试覆盖率数据，并且通过API读取覆盖率数据展示在各种地方，比如展示在README中。

https://app.codecov.io/gh/qqxx6661/log-record/commits

一份可信的更新日志

大部分项目都必要有明确的Release Log/Update Log，用来向用户展示堆栈的特性更新和标题修复，也可以或许记载一起以来项目的迭代更新进程。
恰巧最近正在学习reactor，发现其子项目的一个非常标准的Release Log
https://github.com/reactor/BlockHound/releases

善用其他包装

在Github上，另有一些包装项目的好办法，Github支持organizations，个人可以注册一个虚拟的组织，用组织的名义建立开源项目，往往更有说服力。
https://github.com/settings/organizations

使用其免费版本即可，对于一个开源项目来说基本够用。

Github的更新还是比较频繁的，及时跟上Github新的功能和特性，也许会对你的项目有更多的帮助。
适当宣传

当你的项目有了一个最底子的雏形时，你可以慢慢开始你的宣传工作。还是那句话，不要觉得宣传有什么可耻的，如果一个项目不停不被人瞥见，你也会很快失去动力。那么你会更容易半途而废。
对于个人小项目，有一些常规的推广方式：

• 技能公众号推广：比如向一些有流量的大公众号主做推荐，投放。
  
• 到场技能社区推广：发布文章&到场运动
  
• Github和Gitee运动推广
  

开源是个苦力活

最后一个章节，我们聊聊，做一个开源项目，我们到底为了什么？出名？纯粹好玩？实现个人价值？表现开源精神？赚钱？还是...老实说，开源真的是个苦力活。
不要等待经济回报，请用爱发电

如果你的开源项目已经在稳定维护，并且有一定的用户正在使用，那么恭喜你，项目走上了正轨。但是必要泼冷水的是，大部分就算是有名的开源项目，很多时候是没法给你带来等价的商业回报的，你很大概在很长一段时间里都在用爱发电。
它能给你的告急是成就感和一点小小的着名度，以及这些着名度背后大概带来的一些附加价值（这就很难去描述了）。
如果你真的想要通过它得到一些款项回报，那在你的项目小有名气后，以下几种方式大概会有效果：

• 提供有偿技能支持。
  
• 打造商业版本，区别于社区开源版，商业版闭源并向用户收费。
  
• 寻找一些推广商，在你的项目代码堆栈和文档中植入其“广告”。
  
• 其他野路子...
  

这些事情的背后都要大量的时间和精力去推动，如果你和我一样是一个上班族，那么大概率你没法同时兼顾工作和维护一个持续保持活跃的大型项目。所以很大大概是，你的项目在很长时间内不停是一个小而美的项目。
伸手党

当你的项目有了流量，被很多开辟同学搜索到了，你会获得很多流量附带的东西。
伸手党就是其中一个，具体来说就是有很多网友，会要求你添加很多他们能想到的功能或者他们觉得你项目应该提供的功能。
遇到这种情况，你必要用心判断，他们所要求你添加的功能是否背离你本身项目的初衷，如果是，那么请忽视这些建议。如果是合理的功能，那么请考虑加入，但是可以和用户说明，会在下一个里程碑中加入，不要让用户过于等待你能很快完成。（如果用户真的很渴望能立马用到此功能，你可以建议他本身开分支提交PR）。
无穷无尽的ISSUE

除了伸手党之外，还会有很多用户在ISSUE区问很多标题，例如我的log-record堆栈下这些例子。很多时候，用户对你的项目不熟悉，自然会有一些提问，当遇到重复的提问时，要有耐心，你可以尽量关联到重复标题的老ISSUE上，让他们本身跳过去看。

此外，善用Github提供的各种标签，归类功能，把ISSUE分类，也是间接给用户到场感，让他们知道你正在跟进处置惩罚这些标题。

左右为难的PR

ISSUE虽然比较多并且你很大概觉得有些毫无意义，但是毕竟他们只是用户的提问或者给出建议，我们可以选择是否担当。
但是PR实在是比较尴尬的标题，很多用户的PR很大概是对你的代码进行了很大的改动，有时候这些改动你实在并不愿意担当。但是有的PR，用户花了精力和心思对你的代码进行了大面积的改造（至少在他们心田，这些改造黑白常好的）。
这种情况下，大家都会感觉到进退维谷，如果担当PR，大概代码有些地方就和你预想的越来越偏，如果不担当，就显得不近人情。这种情况，我也没有想好非常好的对策，目前我的策略，是实验做一个冷血无情的。如果与这个提PR的用户另有很多交流，那就尽量用你对项目的见解和他进行交流，让他按照你的要求更改，或者是让她本身fork你的项目，自成一派。
像一些大型的项目，它们也有很多PR没有被担当，且长时间搁置在那边，例如SpringBoot
https://github.com/spring-projects/spring-boot/pulls

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。