开源项目README目录规范

README文档的组成部分

看过很多开源框架的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。 开源许可区别如下图:

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏自动化测试

DIY自动化测试【智能音箱】

    笔者从事智能音箱系统测试,这是一款基于android系统的智能语音助手产品。基本功能特性和测试方法都已稳定,目前多产品快速迭代,涉及的场景较多且数据量大...

1K4
来自专栏微服务

电商前端交易型系统设计原则

个人认为设计系统要因场景因时间而异,一个系统不是一下子就设计的非常完美,在有限的资源情况下一定是先解决当下最核心的问题,并预测/发现未来可能出现的问题,一步步解...

1031
来自专栏云加头条

韩伟:解谜腾讯游戏海量服务架构

网络游戏和其他互联网服务一样,需要面对承载海量用户的压力,同时还需要满足游戏所要求的低延迟、业务逻辑高复杂度的特性。腾讯游戏研发部资深架构师韩伟为大家带来了“解...

5539
来自专栏Java架构师历程

微服务架构是什么

架构师在软件行业一直有很高的位置,并且在开会中的架构师都带有主角光环。 架构师是可以说是软件的设计者,运用我们学会就会忘记的23种设计模式、企业架构模式、面向对...

6292
来自专栏韩伟的专栏

如何设计运维友好的服务器端系统

如果我们在开发的时候,就充分考虑到系统的运维需求,就算只进行了一些简单的约束,都能让运维工作有巨大的改进。我想这也是所谓DevOps流行起来的原因吧。

6350
来自专栏技术翻译

理解分布式系统的8个谬误

你在分布式系统上工作吗?微服务,Web API,SOA,Web服务器,应用服务器,数据库服务器,缓存服务器,负载均衡器 - 如果这些描述了系统设计中的组件,那么...

1612
来自专栏腾讯云技术沙龙

杨原:腾讯云Kafka自动化运营实践

下面我们有请腾讯云基础架构部高级工程师杨原给我们带来主题分享——腾讯云Kafka自动化运营实践。

1.2K13
来自专栏云计算D1net

横向扩展的NAS:混合云存储的关键

目前,世界上大多数的数据中心仍然使用垂直缩放的存储解决方案,这是一个困扰人们的问题。这种传统的存储方法在设计时并没有考虑到现在达到泽字节的庞大数据。企业以往任何...

5298
来自专栏Golang语言社区

我们是怎么做Code Review的

前几天看了《Code Review 程序员的寄望与哀伤》,想到我们团队开展Code Review也有2年了,结果还算比较满意,有些经验应该可以和大家一起分享、探...

3553
来自专栏北京马哥教育

Python3爬虫抓取网易云音乐热评实战

? 前一段时间刚刚入门python爬虫,有大概半个月时间没有写python了,都快遗忘了。于是准备写个简单的爬虫练练手,我觉得网易云音乐最优特色的就是其精准的...

5436

扫码关注云+社区

领取腾讯云代金券