README.md 如何规范 - 开源项目中必不可少的文件
2017-08-16 10:43
260 查看
我们在项目中常常看到README.md 当然扩展名可能是txt ,rb,md ,甚至 me 都有可能.
其实这个小小的静态文件还是有些重要信息可以传递的.
这就是你在github上创建一个项目的是,总会提示你要不要生成一个README.md 文件.
README 应该是介绍code source 的一个概览.其实这个静态文件是有约定成俗的规范.
你的项目介绍
你的代码实现了什么功能?
该如何使用? (系统环境参数,部署要素)
代码组织架构是什么样的?
版本更新重要摘要
如果你的README包括上面的内容,那么当使用者拿到代码,打开README后,基本就知道该如何下手了.如下 README.md :
当然这不是一个固定的范本,有的人甚至把开原协议也写进来.有的人喜欢把changeLog 独立拿出来再创建一个CHANGELOG.md 的文档.
但是必要的项目介绍,使用,部署及代码结构还是很有必要列出来的.
其实这个小小的静态文件还是有些重要信息可以传递的.
这就是你在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 的文档.
但是必要的项目介绍,使用,部署及代码结构还是很有必要列出来的.
相关文章推荐
- 如何为开发项目编写规范的README文件(windows)
- 如何编写github项目的README.md文件?
- 如何为开发项目编写规范的README文件(windows),此文详解
- 如何为开发项目编写规范的README文件(足球竞猜源码下载),此文详解
- github—如何在README.md文件中添加图片
- android studio和github进行关联和如何向README.md文件中添加图片说明
- zhihu-spider开源项目的README.md
- android studio和github进行关联和如何向README.md文件中添加图片说明
- 如何上传图片到github并在README.MD文件中显示
- 如何编写开源项目的 README 文档
- 为项目编写Readme.MD文件
- 为项目编写Readme.MD文件
- 打开开源项目总得.md文件
- (转)为项目编写Readme.MD文件
- github—如何在README.md文件中添加图片
- 关于如何在github的README.md文件内添加图片的教程
- 如何在README.md文件中添加图片
- 为项目编写Readme.MD文件
- 为项目编写Readme.MD文件(转自OneCoder)
- 为项目编写README.md文件