看过很多开源框架的README文档,综合一下,项目简介要说明几个你的开源项目用户想迫切了解的问题,这包括:
这个开源项目是做什么的? 这个项目是什么语言编写的? 项目维护、CI、依赖更新状态 项目可用版本及其他版本 Demo 或官网地址
所以总结了大概有以下几部分组成:
(一)国际化 (二)项目工程介绍 (三)项目的使用效果图 (四)项目特点 (五)项目的基本结构(架构) (六)集成方式 (七)使用方法 (八)混淆(可选) (九)关于作者/组织及交流方式等信息 (十)贡献者/贡献组织 (十一)鸣谢 (十二)版权信息
Github是面向全球的一个开源网站,所以不要局限于中文文档,建议写一个英文的README,让来自全球的人都能更方便的了解你的项目。推荐写法,在REAMDE开头写上国际化引用地址:
此外你还可以给项目上面增加一些图标以提高可读性,推荐使用 Shields.io,比如:
让别人快速了解项目。项目介绍主要包括:
项目名称、logo(没有logo就不写):这里推荐一个在线制作 Logo 的网站 Canva
效果图如下所示:
如果是一些自定义控件或者项目的演示效果的,基本都会放上演示效果图,可以是图片,也可以是gif图。 建议:静态的页面的放截图,交互很复杂的建议放gif图。
注明这个项目的功能特点,亮点特色会大大提高访客使用这个项目的概率。
比如效果图:
这里主要介绍项目的各个组成部分,如果是框架,可以附带架构图解;如果是其他的,可以提供一些UML分析图,顺便分析一下源码也行的。
这是 README 中最重要的部分,你需要说明这个项目如何使用,这包括:
如何下载这个项目:一般情况下 git clone 该项目地址即可,当然你也可以提供其他包管理下载安装方式; 运行环境:需要的不同环境 项目依赖:你需要说明编译运行这个项目前需要哪些依赖; 安装:你需要说明如何编译安装/运行这个项目; 部署:如果这个项目可以部署的话,请最好注明部署要注意的事项; Debug 方法:理想状况下,你的用户会顺利编译并运行这个项目,但你要确保用户遇到了问题不会来打扰你(如提交 Issues),你还需要提供用户可能会遇到的常见问题;
效果: 工作环境:
如何拉取项目:
安装:
测试debug:
可以写一下作者或者组织的联系方式,微信,邮箱,博客,微博,甚至支付宝转账二维码等都是可以放上去的。
对于一个开源项目来说,令其作者最开心的莫过于有人提交 Pull Request 了。加入一个 CONTRIBUTING 文档将大大提高他人贡献你的项目的概率。
你可以说明你的代码规范,项目架构,如何测试和提交 Pull Request 的正确格式,以及其他有利于开发者进行贡献的信息,这将会使你的项目变得更加的规整如一。你可以在项目根目录新建一个 CONTRIBUTING 进行详细的说明并在 README 中添加其文件锚链接。
比如:
引用了哪些开源技术,这里可以做一些鸣谢,表示对别人的尊重,其实也是一个引用声明,避免因为版权而引起不必要的纠纷。
版本很重要,开源许可证很重要,如果没有生命版权,可能会因为一些侵权行为而无法很好的维权,版权信息可以保护作者的权益(个人理解)。
世界上的开源许可证,大概有上百种。很少有人搞得清楚它们的区别。最流行的有六种:GPL、BSD、MIT、Mozilla、Apache、LGPL。 开源许可区别如下图: