如何写一个通用的README规范

背景

咱们日常在进行项目开发时，通常都会把代码上传至代码托管平台上方便管理和维护。目前你们使用的托管平台最多的仍是Github，国内外还有一些比较知名的代码托管平台，好比Gitlab、BitBucket，码云和码市等。

但咱们在多人合做开发下，常常碰到的最头疼的问题是，其余开发者在交接给咱们一个项目时只是对项目目前现有的功能简单的描述了下，咱们在后续迭代功能时忽然发现连最基本的项目如何运行都没有给咱们交代，当时心中一万只那个什么马奔腾而过，只能去查看package.json的scripts，本身意会了。

那么问题来了，咱们在交接一个项目时，如何保证项目能快速完整地交付给基友，今后过上无忧无虑的生活呢？答案是咱们只须要甩给他一份标准规范的README。

• • -

规范的README须要哪些内容

咱们经过一张截图一块儿来看看一份简单的README规范都有哪些内容：

上面的readme规范模板在咱们 feflow的 README规范里能够看到

• • -

那么咱们一块儿来探讨下，一份规范完整的README规范都应该有哪些内容呢？

1. 项目描述
2. 如何运行
3. 业务介绍
4. 项目备注

每一项都有哪些做用？

• 项目描述

  须要说明咱们的项目名，项目功能简述，代码仓库地址，以及该项目的第一负责人。谁交接给咱们的项目，谁就是该项目的第一负责人。

• 如何运行

  1. 开发环境配置。通常是咱们须要的一些运行环境配置。
  2. 开发&发布 命令。咱们怎么经过命令开启本地开发，以及构建发布。
  3. 代理配置。若是咱们的项目在本地开发时须要用到一些代理工具，例如fiddler或whistle等，咱们须要列出代理的配置项。最好是直接导出一个代理配置的文件，放在项目下
  4. 发布。若是咱们有用到一些发布平台，最好贴上项目的发布模块和发布单，减小咱们发布的时间成本。
  5. 错误告警及监控。相信咱们日常都会对线上的项目部署错误告警和监控日志的服务，方便咱们及时排查现网问题，这里咱们能够加入项目的一些监控属性ID
  6. 接口API。这里咱们须要贴入项目中拉去的后台接口地址以及描述，还有咱们的接口负责人，当后台服务异常，能够直接联系到后台同窗。
  7. 数据上报。咱们在日常项目里都有加入一些数据上报，给产品同窗统计业务数据用，这里咱们最好阐述下都有哪些数据的上报。若是上报出问题，产品妹子找过来，咱们不至因而一脸懵逼。

• 业务介绍

  对于前端来讲，咱们一个项目可能不止一个页面，那么咱们须要给出如下信息:

  1. 业务入口地址及渠道连接 即咱们整个项目的入口页面，或者比较重要的页面地址。通常入口页面，咱们可能会在多个渠道进行投放，那么须要列出全部的渠道连接

  2. 各页面及描述 列出咱们项目内的全部页面信息，好比下面这样：

     页面目录	页面描述	页面连接	参数描述
     index	首页	https://now.qq.com	无

• 项目备注 项目中须要告诉其余开发者一些关键信息，好比咱们页面打包构建，须要注意哪些问题等等，这些信息虽然不是必须的，可是能够帮助其余开发者下降开发的风险成本。

最后

上面是咱们一个规范的README所需的一些信息和内容，加粗内容是我认为README里的一些必需信息，你们也能够在此基础上针对本身项目实际的开发场景来扩展一些规范信息。

腾讯IVWEB团队的工程化解决方案feflow已经开源：Github主页： https://github.com/feflow/feflow

若是对您的团队或者项目有帮助，请给个Star支持一下哈～