README.md 如何规范 - 开源项目中必不可少的文件

我们在项目中常常看到README.md 当然扩展名可能是txt ,rb,md ,甚至 me 都有可能.

其实这个小小的静态文件还是有些重要信息可以传递的.

这就是你在github上创建一个项目的是,总会提示你要不要生成一个README.md 文件.

README 应该是介绍code source 的一个概览.其实这个静态文件是有约定成俗的规范.

1. 你的项目介绍

2. 你的代码实现了什么功能?

3. 该如何使用? (系统环境参数,部署要素)

4. 代码组织架构是什么样的?

5. 版本更新重要摘要

如果你的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 的文档.

但是必要的项目介绍,使用,部署及代码结构还是很有必要列出来的.