背景

我们平常在进行项目开发时,一般都会把代码上传至代码托管平台上方便管理和维护。目前我厂使用的托管平台是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. 业务入口地址及渠道链接 即我们整个项目的入口页面,或者比较重要的页面地址。一般入口页面,我们可能会在多个渠道进行投放,那么需要列出所有的渠道链接

    1. 各页面及描述 列出我们项目内的所有页面信息,比如下面这样:

      页面目录 页面描述 页面链接 参数描述
      index 首页 https://xxx.com
  • 项目备注 项目中需要告诉其他开发者一些关键信息,比如我们页面打包构建,需要注意哪些问题等等,这些信息虽然不是必须的,但是可以帮助其他开发者降低开发的风险成本。

如何写一个通用的README规范的更多相关文章

  1. 一起学习造轮子(一):从零开始写一个符合Promises/A+规范的promise

    本文是一起学习造轮子系列的第一篇,本篇我们将从零开始写一个符合Promises/A+规范的promise,本系列文章将会选取一些前端比较经典的轮子进行源码分析,并且从零开始逐步实现,本系列将会学习Pr ...

  2. 写一个通用的List集合导出excel的通用方法

    前几天要做一个数据导出Excel 我就打算写一个通用的. 这样一来用的时候也方便,数据主要是通过Orm取的List.这样写一个通用的刚好. public static void ListToExcel ...

  3. 《用Java写一个通用的服务器程序》01 综述

    最近一两年用C++写了好几个基于TCP通信类型程序,都是写一个小型的服务器,监听请求,解析自定义的协议,处理请求,返回结果.每次写新程序时都把老代码拿来,修改一下协议解析部分和业务处理部分,然后就一个 ...

  4. Tsx写一个通用的button组件

    一年又要到年底了,vue3.0都已经出来了,我们也不能一直还停留在过去的js中,是时候学习并且在项目中使用一下Ts了. 如果说jsx是基于js的话,那么tsx就是基于typescript的 废话也不多 ...

  5. 【github】论怎么去写一个高大上的ReadMe

    前言 以前我时常觉得,自己写的ReadMe很单调乏味,但后来仔细研究一下后,发现有很多方式可以让ReadMe在简洁的基础上变得好看些,所以在这里和大家分享,如果大家有更好的想法,也非常欢迎在评论区留言 ...

  6. 一步一步写一个简单通用的makefile(四)--写一个通用的makefile编译android可执行文件

    通常要把我们自己的的代码编译成在android里面编译的可执行文件,我们通常是建一个文件夹 . ├── Android.mk ├── Application.mk ├── convolve.cl ├─ ...

  7. 《用Java写一个通用的服务器程序》02 监听器

    在一个服务器程序中,监听器的作用类似于公司前台,起引导作用,因此监听器花在每个新连接上的时间应该尽可能短,这样才能保证最快响应. 回到编程本身来说: 1. 监听器最好由单独的线程运行 2. 监听器在接 ...

  8. 《用Java写一个通用的服务器程序》03 处理新socket

    在讲监听器时说过处理的新的socket要尽快返回,监听器调用的是ClientFactory的createPhysicalConnection方法,那么就来看这个方法: public boolean c ...

  9. 用C#开发的一个通用的地铁换乘查询工具

    日常生活中,上班下班坐地铁已经是常事,每当我想去某一个远一点的地方,如果有地铁首选就是地铁,因为方便嘛!每次坐地铁,我们都是凭肉眼去得出我们心中最佳的换乘方案,但是,如果对于线路较少的城市来说,这个方 ...

随机推荐

  1. 老男孩python学习自修第十三天【md5加密】

    示例代码如下: hashlib_test.py #!/usr/bin/env python # _*_ coding:UTF-8 _*_ import hashlib def genPasswd(na ...

  2. qtp 自动化测试--点滴 菜单没有了,有些控件运行时找不到

    test项目页签下-没有了 菜单栏:file edit view insert 看不到了 1 解决:在startpage标签下-tool-option-点击 restore layout-确定 2 菜 ...

  3. Using MongoDB with Web API and ASP.NET Core

    MongoDB is a NoSQL document-oriented database that allows you to define JSON based documents which a ...

  4. hdu-4763(kmp+拓展kmp)

    题意:给你一个串,问你满足最大字串既是前后缀,也在字符串除去前后缀的位置中出现过: 思路:我用的是拓展kmp求的前后缀,只用kmp也能解,在字符串2/3的位置后开始遍历,如果用一个maxx保存前2/3 ...

  5. linux 目录分类与文件操作

    / 虚拟根目录 一般不会在这里存储文件 /bin 二进制目录,存放需要GNU用户级的工具 /boot 启动目录,存放启动文件 /dev 设备目录,linux在这里创建设备节点 /etc 系统配置文件目 ...

  6. 了解AutoCAD对象层次结构 —— 3 ——数据库

    数据库的结构是什么样的?对象是如何存储在数据库中的?这些问题我们需要搞明白.在此我们可以借助工具ArxDbg或MgdDbg来查看数据库结构及其内容.下图就是利用MgdDbg工具查看到的内容,我们可以看 ...

  7. Cmder使用ls中文显示乱码解决方案

    操作系统:Windows 7 旗舰版 Cmder:1.3.2 默认配置不支持使用ls显示中文命名的文件列表. 解决方法: 按下Win+Alt+P打开设置. 在StartUp - Environment ...

  8. python之旅七【第七篇】面向对象之类成员

    面向对象的类成员 相关知识点 一  字段 字段包括:普通字段和静态字段,他们在定义和使用中有所区别,而最本质的区别是内存中保存的位置不同, 普通字段属于对象 静态字段属于类 class Provinc ...

  9. 数据结构与算法(Python)

    一.数据结构与算法概述 数据结构与算法的定义 我们把现实中大量而且非常复杂的问题以特定的数据类型(个体)和特定的存储结构(个体的关系)保存到相应的主存储器(内存)中,以及在此基础上为实现某个功能而执行 ...

  10. ElasticHD Linux环境下安装

    ElasticHD Linux环境下安装教程        ElasticHD windows环境下安装教程   上一篇讲了ElasticHD windows环境下安装,这一篇继续说明ElasticH ...