如何写一个通用的README规范 1

背景

我们平常在进行项目开发时，一般都会把代码上传至代码托管平台上方便管理和维护。目前我厂使用的托管平台是SVN，国内外还有一些比较知名的代码托管平台，比如github、Gitlab、BitBucket，码云和码市等。

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

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

规范的README需要哪些内容

我们一起来探讨下，一份规范完整的README规范都应该有哪些内容呢？

1. 项目描述

2. 如何运行

3. 业务介绍

4. 项目备注

每一项都有哪些作用？

项目描述

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

对于前端来说，我们一个项目可能不止一个页面，那么我们需要给出以下信息:
1. 业务入口地址及渠道链接 即我们整个项目的入口页面，或者比较重要的页面地址。一般入口页面，我们可能会在多个渠道进行投放，那么需要列出所有的渠道链接

各页面及描述 列出我们项目内的所有页面信息，比如下面这样：

页面目录	页面描述	页面链接	参数描述
index	首页	https://xxx.com	无

项目备注项目中需要告诉其他开发者一些关键信息，比如我们页面打包构建，需要注意哪些问题等等，这些信息虽然不是必须的，但是可以帮助其他开发者降低开发的风险成本。

转载于:https://www.cnblogs.com/zhouyangla/p/8977596.html

如何写一个通用的README规范 1相关推荐

如何写一个通用的README规范
背景我们平常在进行项目开发时,一般都会把代码上传至代码托管平台上方便管理和维护.目前大家使用的托管平台最多的还是Github,国内外还有一些比较知名的代码托管平台,比如Gitlab.BitBucke ...
写一个通用数据访问组件
出处:http://www.csharp-corner.com willsound(翻译) 我收到过好多Email来问我如何用一个通用的数据提供者(data provider)在不失自然数据提供者(n ...
java 通用组件_写一个通用数据访问组件
出处:http://www.csharp-corner.comwillsound(翻译)我收到过数据库出处:http://www.csharp-corner.com willsound(翻译) 我收 ...
深入理解Promise并写一个符合Promise a+规范的Promise代码
深入理解Promise并写一个符合Promise a+规范的Promise代码关于Promise函数可以参考我写的这篇文章https://www.cnblogs.com/qiaohong/p/770 ...
写一个符合 Promises/A+ 规范并可配合 ES7 async/await 使用的 Promise
原文地址从历史的进程来看,Javascript 异步操作的基本单位已经从 callback 转换到 Promise.除了在特殊场景使用 stream,RxJs 等更加抽象和高级的异步数据获取和操作流 ...
一步步写一个符合Promise/A+规范的库
Promise本意是承诺,在程序中的意思就是承诺我过一段时间后会给你一个结果. ES6 中采用了 Promise/A+ 规范,Promise 实现之前,当然要先了解 Promise/A+ 规范,规范地 ...
一步步写一个符合Promise/A+规范的库 1
Promise本意是承诺,在程序中的意思就是承诺我过一段时间后会给你一个结果. ES6 中采用了 Promise/A+ 规范,Promise 实现之前,当然要先了解 Promise/A+ 规范,规范地 ...
Markdown 工程师也不简单：如何写一个高逼格 README
最近一个项目从程序员变成了一个高级文档哥,好吧,我还称不上高级,但是我发现写文档真不是一件容易的事情,要怎么写的让人看的舒服.巴适.爽的不行,看完就想给你个赞呢?我也总结了一下写文档的一些感想,也不能 ...
JS-事件-写一个通用的事件监听函数
之前学习总是遇到问题再去研究表面知识,这是不可取的,在这里我们来写一个绑定事件的函数,以此巩固我们对JS事件相关知识点的理解在这里我会解释一下各个参数之间的关系 function bindEvent ...

如何写一个通用的README规范 1

背景

规范的README需要哪些内容

如何写一个通用的README规范 1相关推荐

最新文章

热门文章