README.md 如何规范 - 开源项目中必不可少的文件
--> -->
我们在项目中常常看到README.md 当然扩展名可能是txt ,rb,md ,甚至 me 都有可能.
其实这个小小的静态文件还是有些重要信息可以传递的.
这就是你在github上创建一个项目的是,总会提示你要不要生成一个README.md 文件.
README 应该是介绍code source 的一个概览.其实这个静态文件是有约定成俗的规范.
你的项目介绍
你的代码实现了什么功能?
该如何使用? (系统环境参数,部署要素)
代码组织架构是什么样的?
版本更新重要摘要
如果你的README包括上面的内容,那么当使用者拿到代码,打开README后,基本就知道该如何下手了.如下 README.md :
DEMO
===========================
###########环境依赖
node v0.10.28+
reids ~
###########部署步骤
1. 添加系统环境变量
export $PORTAL_VERSION="production" // production, test, dev
2. npm install //安装node运行环境
3. gulp build //前端编译
4. 启动两个配置(已forever为例)
eg: forever start app-service.js
forever start logger-service.js
###########目录结构描述
├── Readme.md // help
├── app // 应用
├── config // 配置
│ ├── default.json
│ ├── dev.json // 开发环境
│ ├── experiment.json // 实验
│ ├── index.js // 配置控制
│ ├── local.json // 本地
│ ├── production.json // 生产环境
│ └── test.json // 测试环境
├── data
├── doc // 文档
├── environment
├── gulpfile.js
├── locales
├── logger-service.js // 启动日志配置
├── node_modules
├── package.json
├── app-service.js // 启动应用配置
├── static // web静态资源加载
│ └── initjson
│ └── config.js // 提供给前端的配置
├── test
├── test-service.js
└── tools
###########V1.0.0 版本内容更新
1. 新功能 aaaaaaaaa
2. 新功能 bbbbbbbbb
3. 新功能 ccccccccc
4. 新功能 ddddddddd
当然这不是一个固定的范本,有的人甚至把开原协议也写进来.有的人喜欢把changeLog 独立拿出来再创建一个CHANGELOG.md 的文档.
但是必要的项目介绍,使用,部署及代码结构还是很有必要列出来的.