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 的文档.
但是必要的项目介绍,使用,部署及代码结构还是很有必要列出来的.