项目交接规范

如果你新加入一个项目的开发,在交接文档不齐全的情况下,相信少不了无从下手的烦恼,为了解决这个问题,本文对项目交接文档做一个简单的约定(Inspired By 项目交接中所踩的坑 & 全栈指引平台)。

项目相关

资源

说明:

介绍项目开发所涉及的资源,包括代码和文档地址(从地址可以看出代码管理工具是 git 还是 svn)、系统登录地址及账号(如果已上线的话)、对接人员等。

示例:

代码路径:

文档路径:

系统登录地址:

账号 & 密码:

对接人员:

  • 交互:
  • 前端:
  • 后台:
  • PD:

安装调试

说明:

介绍环境依赖及安装方法,并且:

示例:

  1. 下载和安装 Node(version >= 4.0)
  2. 安装 tnpm npm install -g tnpm --registry=http://registry.npm.alibaba-inc.com(如果报错,请先运行 sudo chown -R $USER /usr/local
  3. 从代码库更新代码 git clone xxx
  4. 安装依赖 cd xxx && tnpm install
  5. 运行 tnpm run dev,访问 http://127.0.0.1:xxxx

代码相关

代码结构说明

说明:

介绍每个有可能被二次改动的目录及文件的作用

示例:

--project
  |--src(源代码目录)
    |--common(通用组件库,包括通用网络请求、工具函数等)
      |--lib.js
      |--util.js
    |--component(业务组件库,可通过文件结构划分业务逻辑模块)
      |--index.jsx
      |--index.less
    |--entry(入口文件,可以有多个)
      |--index.jsx
  |--.eslintrc(提交前的语法配置检查)     
  |--.gitignore(git 提交的文件过滤配置)
  |--package.json(项目信息文件,包括依赖包和构建命令)
  |--index.html(调试的入口页面)

技术栈及快速入门

说明:

介绍开发涉及的环境、工具、语言,并对需要项目交接人员深入了解的部分给出快速上手文档,因为你不能保证新加入项目的成员对这些技术都了解,根据你的经验给出入门文档可以帮助他们节省很多时间。

示例:

环境:

构建工具:

代码管理工具:

开发语言:

单元测试:

开发相关

需要改动的代码位置

说明:

介绍需要添加或修改的代码所在目录位置和文件位置

示例:

vm 模板:

  • 修改 a/b/c/auth.vm
  • 修改 a/b/c/authMobile.vm

js:

  • 在 public/js/ 下新建 auth.js 文件

css:

  • 修改 public/css/auth.css
  • 修改 public/css/authMobile.css

部署上线

说明:

介绍项目部署和上线的流程

示例:

本项目为纯前端资源,部署上线可参考:

前端应用申请

前端应用发布

一个典型操作的完整流程

说明:

如果是一个规模庞大,持续时间长,参与人员多的项目,提供一个典型操作的完整流程是很有必要的。比如对于 DPL 项目,可以提供一个简单组件的开发过程。

示例:

(以开发一个企业应用前端服务化组件为例)

搭建环境:

  1. 安装 node 和 tnpm
  2. 全局安装 seek-bin 脚手架:tnpm install @ali/seek-bin -g

开发组件:

a. 为组件创建目录,运行脚手架

mkdir 组件名称 (如果是系统组件,推荐 系统名-组件名,组件名第一个字母大写) 
cd 组件名称
seek-bin init

b. 脚手架目录说明

  • doc 使用文档
  • lib 组件依赖库
  • src 组件源码

c. 组件调试

运行 seek-bin server 会自动打开浏览器页面调试

d. 组件发布

tnpm publish

常见问题

说明:

对项目开发时的常见问题做一个总结,并给出解答。

示例:

a. 安装 tnpm 时报错

如果出现了类似 Error: EACCES: permission denied 的错误, 执行 sudo chown -R $USER /usr/local 然后重新执行安装命令

b. 运行 tnpm run dev 报错

1)如果遇到提示 can not find module xxx 或类似未找到 module 的报错,说明在运行 tnpm install 安装时候可能没有成功,可以尝试单独安装模块解决这个问题,即 tnpm install xxx

2)遇到 Error: listen EADDRINUSE :::8000(或者其他数字) 说明已经启动了一个 server,相应 8000 的端口被占用了,你可以找到之前开的 server,control + c 然后重新 run dev; 如果找不到之前开的 server,请先使用 lsof -i tcp:8000 找到进程号 PID,比如 12642,再执行 kill 12642 来结束该进程。

坚持原创技术分享,您的支持将鼓励我继续创作!