Introduction——介绍项目
项目名称,logo, 介绍项目背景和涉及业务。
Features
再接下来,一个好的项目简介,能够帮助使用者了解他能够使用这个工具干什么,能不能满足自己的需求。一般来说,我们希望从简介中,了解下面一些信息:
- 什么语言写的?Node、Python 还是其他什么
- 这个项目的用途是什么
- 最新版本信息
- 构建、测试结果等信息
- Demo 演示地址或者官网
Installation——安装
这部分是告诉使用者如何快速开始使用。
首先,告诉用户如何去获取以及初始化项目,例如:
|
Examples——示例
一个简单的例子告诉开发者如何使用,就像下面这样:
|
API Documentation——API文档说明
这里用于说明项目对外的API,对于一个API,应该描述清楚以下几点:
- 作用
- 入参及每个参数是否必须,数据类型是什么等等
- 返回值
如果API不多,可以在这里列出,如果很多,则建议放到单独的文件中,这里放一个链接即可。
Changelog
最好要有一份CHANGELOG文档,对不同版本做了哪些修改,有什么特性等等作出说明,让用户知道每个版本都做了些什么。一般放置在单独文件中,这里只放一个链接。
Contributing——贡献指南
这里用于说明如何参与项目开发以及项目开发中需要遵守的规范。
Branch Organization——分支管理
说明项目的分支命名及使用规范
Git Commit Guidelines
git commit的规范,可以参考Git Commit Guidelines。
Development Workflow——开发流程
说明参与项目开发的流程以及项目中JS以及CSS的一些规范,一般情况下js都统一使用standardjs规范。
贡献指南可以参考ant-design的贡献指南
License
说明项目使用什么开源协议,一般为 MIT。