理工新源开发规范手册-试行版 V1.4

部门文档

[TOC]·

变更历史

1 公共资源

2 开发工具

为了规范公司内部开发流程，对于开发工具版本进行统一要求.

samb共享服务器

• 用户名： lgxy
• 密码： 123456.lgxy

3 编码规范部分

参考阿里巴巴Java开发手册

4 Git版本控制

4.1 使用规范

4.1.1 修改提交用户名和Email

开发人员应配置自己的姓名和和公司邮箱，user.name用拼音全拼，邮箱用公司邮箱

git config --global user.name "Your Name"
git config --global user.email you@example.com

4.1.2 规范commit信息

公司要求强制规范开发人员的commit，否则代码不允许提交。

• 用一空行分隔标题与正文。
• 标题使用大写字母。
• 标题不超过50个字符。
• 标题使用祈使语气。
• 标题不要使用句号结尾。
• 正文在72个字符处换行。
• 正文解释是什么和为什么，而不是如何做。
• 正文每行以-开头

示例

新增导入功能，修改用户姓名和用户密码长度等        
- [add] 用户管理增加导入功能  
- [modify] 将用户姓名最大长度改为20字符
- [remove] 移除自定义数据项模块
- [bug-1003] 新增时存在xxxx问题                      //对应禅道上的bug号
- [bug] 修改用户时xxxx问题                          //开发人员自己发现的bu

4.1.3 撤销commit信息

开发人员如果事先没有按照规范填写commit，需要对commit进行修正，可以通过git commit –amend处理，注意，git commit –amend只处理本地最后一次commit的。

若本地存在多个commit，可以先通过如下指令处理下

# 先重置, `--soft`回退了commit的信息，不回退文件
git reset --soft id
# 再执行
git commit –amend

4.2 Git 常用操作

4.2.1 初始化Master

1、通过终端，转到项目目录，通过如下命令创建git暂存区

git init

2、将相应的文件和目录增加增到暂存区，如有多个文件，可以用空格分隔开来

git add src pom.xml README.md

3、提交项目到本地的仓库。注意：此时操作还没提交到远程仓库

git commit -m '版本初次提交' #提交信息需要认真填写 

4、创建一个远程仓库

git remote add origin http://218.205.184.127:8080/chenpeng/veh-ts.git

5、 将本地仓库推送到远程仓库分支，这里应为master

git push origin master

如果存在冲突，可以先拉取最新的，然后再推送

git pull origin master --allow-unrelated-histories

4.2.2 分支操作

1、查看远程仓库的分支列表

git branch -a

2、查看本地分支

git brach

3、创建本地分支

git branch release-1.0  #分支版本号为release-1.0

4、推送到远程仓库

git push origin release-1.0

5、切换到分支

git checkout release-1.0

4.2.3 发版操作

在以下几种情况，开发人员需要进行发版操作，即通过git tag进行操作:

• 测试通过（以测试为准）
• 生产环境验证通过(测试环境不具备测试条件，需要在生产环境直接验证)

git tag主要用于标识提测版本号，每次提测后，都应该新增一个tag，对应提测版本号。下面列出显示的git tag操作，详细的可以查看git相关说明。

1. 列出所有标签

$ git tag
v0.1
v1.3

1. 查找标签

$ git tag -l 'v1.4.2.*'
v1.4.2.1
v1.4.2.2
v1.4.2.3
v1.4.2.4

1. 新增标签

$ git tag -a v1.4 -m '关于当前版本的说明'    // v1.4即版本号

1. 显示标签

$ git show v1.4
tag v1.4
Tagger: Scott Chacon <schacon@gee-mail.com>
Date:   Mon Feb 9 14:45:11 2009 -0800
关于当前版本的说明
commit 15027957951b64cf874c3557a0f3547bd83b3ff6
Merge: 4a447f7... a6b4c97...
Author: Scott Chacon <schacon@gee-mail.com>
Date:   Sun Feb 8 19:02:46 2009 -0800
    Merge branch 'experiment'

1. 推送tag
   git push并不会把tag标签传送到远端服务器上，只有通过显式命令才能分享标签到远端仓库。要想推送tag到远程仓库，需要进行如下操作：

git push origin [tagname]

5 Phabricator使用说明

Phabricator 是一套快速、可扩展、完全开源的，完整的开发软件工具。
它内置的应用程序，可以帮助您管理任务；审查代码；托管 Git、SVN 或 Mercurial 仓库；构建与持续集成；审查设计；在内部聊天室进行讨论等等。

5.1 基本使用

5.1.1 激活

用户账号由管理员开通，不提供用户注册功能。管理员开通，系统会发送一封开通账号的邮件到邮箱中，然后用户按照邮件提示，点击相关链接，设置用户密码即可。

系统可能由于邮件服务原因，导致用户收不到邮件。如发生此情况，直接找管理员提供链接即可

5.1.2 登录

使用浏览器打开http://review.bitnei.cn:8080,即可以看到系统的登录页面的，输入管理员提供的用户名和密码，即可登录进入Phabricator系统。

5.1.3 修改语言环境

Phabricator支持多语言环境，不过官方并不提供简体中文，当前系统的中文支持是第三方提供的汉化资源文件。如需切换语言环境，请按下面操作流程

1、点击右上角的Setting,即设置，点击用户个人设置界面。

2、点击Account，在Transalation选择合适自己的语言环境，然后保存设置即可。

5.1.4 修改登录密码

在个人设置中，找到密码菜单项，按系统操作提示，进行修改密码即可。

5.1.5 修改VCS密码

VCS密码即是Git、SVN等仓库的密码，在Phabricator系统，登录密码和VCS仓库密码是分开的，并且要求登录密码和VCS不能一致。

在个人设置中，找到VCS密码菜单项，按系统操作提示，进行修改密码即可。

5.1.6 浏览代码仓库

用户可以在Phabricator系统中查看仓库信息，浏览代码，以及仓库相关的所有信息，包括仓库的地址。

1. 找到仓库菜单栏
   

2. 查看当前权限能查看到的所有仓库

1. 查看仓库克隆地址

5.1.7 登出

在右上角的设置，直接点击Log out xxx，即可以注销退出当前系统

5.2 Code Review

Phabricator提供了代码审查和审计两个功能模块，供用户进行Review工作，进而保证代码质量，提升产品质量。在这里，先对审查和审计区别进行简单描述：

• 审查：代码推送前，对代码进行review工作。审查策略可以灵活定义，根据项目和人力情况，配置审查策略。常用的审查策略：

  • 按人： 即设定某个开发人员的代码，必须经过审查，才能进行代码提交
  • 按仓库：即设定某个仓库的代码，必须经过审查，才能进行代码提交
  • 按项目：即设定某个项目的所有仓库代码，必须经过审查，才能进行代码提交

• 审计：代码推送后，项目主要负责人及质量把控人员，可以对提交的代码审计。审计人员对代码提示疑虑后，开发人员需要作出解释及改进，处理完之后，审计人员将审计关闭。

更详细的审计和审查的区别，参见官方说明用户手册: 代码审查和审计

5.2.1 代码审查(推送前)

5.2.1.1 安装Arcanist

详细的可以直接参见官方文档Arcanist 快速开始

1. 下载相关组件

为了快速配置，我们固定将组件存入到E:\review目录（默认的windows命令行可能不支持mv操作，如果不行，直接通过拷贝实现）

#
cd e:
#下载组件，
git clone http://review.bitnei.cn:8080/source/phabriatorConfig.git
# 重命名目录
mv phabriatorConfig e:\review

1. 配置环境变量

将php和arcanist的可执行目录增加到PATH，即如下图：

1. 测试
   

5.2.1.2 项目配置

要求在项目根目录，创建一个.arcconfig文件(此工作应由工程负责人处理，然后提交到git仓库上)，配置内容如下

{
  "phabricator.uri" : "http://review.bitnei.cn:8080/"
}

5.2.1.3 审查流程

审查流程介绍可参见官方文档Differential 用户指南

5.2.1.3.1 提交审查

1. 通过git add 将新增变更的文件加入到本地缓存

1. 通过git commit将变更提交到本地仓库

1. 执行arc diff将变更代码提交到phabricator，供审核人员审核

若当前项目存在未增加到本地缓存的文件，会出现这个提示，在这里，我们输入y即可

然后arc会通过调用外部的编辑器（linux和mac默认会调用vi），对提交的审核信息进行编辑，编辑完之后保存，然后关闭编辑器，arc就会自动将审核内容提交

c. 提交成功

d. 查看提交的审查列表

5.2.1.3.2 审查员审查

1. 审查员登录Phabricator系统，找到等待审查的内容，如下图：

1. 审查员通过浏览对比代码，仔细审查开发人员提供的代码，在审查过程中，可以在代码行增加内嵌评论，操作方式见Differential 用户指南: 内嵌评论
   

5.2.1.3.3 推送代码

1. 通过执行arc list查看审核状态,我们会发现状态已经变为Accepted

1. 通过运行arc land将代码提交到仓库，按照提示输入身份认证信息，即可以提交到仓库

5.2.2 代码审计(推送后)

审计的发起可由开发人员在commit中指定，也可以由审计员通过Phabricator系统浏览代码发起审计。通常情况由审计人员发起。

详细的审计说明见官方文档审计用户指南

5.2.2.1 审查员提出审计

审计员可以直接在仓库中，查看各个commit，然后指出疑虑，即审计

5.2.2.2 开发人员处理

开发人员根据审计人员的意见，需要向审计员作出解释或代码改进。

5.2.2.3 审查员关闭审计

疑虑消除后，审计人员将审计关闭。

6 提测规范

6.1 提测前提

开发人员需要经过自测通过，并且事先和测试人员进行沟通相关测试事宜。

6.2 版本号定义

版本号定义规则为 A.B.C-日期-构建号，如果是企业定制版，则定义为A.B.C-企业简写-日期-构建号

一般来讲大部分的软件版本号分3段，比如 A.B.C
A 表示大版本号，一般当软件整体重写，或出现不向后兼容的改变时，增加A，A为零时表示软件还在开发阶段。
B 表示功能更新，出现新功能时增加B
C 表示小修改，如修复bug，只要有修改就增加C

举例：

• evsmc-2.2.0-20180514-01
  即表示版本号为2.2.0, 创建日期为2018-05-14，第一次构建。

• evsmc-2.2.0-AK-20180514-01
  即表示版本号为2.2.0,AK定制版(取首字母大写)， 创建日期为2018-05-14，第一次构建。

6.3 邮件结构规范

6.3.1 主题

格式： [提测][产品名称]工程代号-版本号，比如[提测][企业车联网平台]evsmc-2.2.0-20180514-01

• 产品名称： 就是当前产品定义的名称，比如企业车联网平台、电池溯源平台
• 工程代号： 一般指工程名称，比如evsmc、kafkaservice
• 版本号： 版本号见6.2 版本号定义

6.3.2 收件人

• 相关测试人员

6.3.3 抄送人

• 产品人员
• 项目经理
• 相关开发人员

6.3.4 邮件主体内容

6.3.4.1 标签说明

• add: 新增的功能项或特性
• modify：功能变更修改，没有录入禅道
• remove: 系统废除的功能
• bug: 系统Bug，包括禅道bug和开发人员自己发现的Bug

以上标签在邮件中，必须按顺序出现，不能出现add在remove之后。

6.3.4.2 正文示例

访问地址、用户名和密码，视系统情况而定，部分提测可能不存在信息。

测试同事：
    你们好，现[企业车联网平台]evsmc-2.2.0-20180514-01 申请提测，访问地址: http://xxx.xxx.xxx.xx/admin/logout,用户名: admin, 密码:123456。
详细提测内容如下：
* [add] 用户管理增加导入功能  
* [modify] 将用户姓名最大长度改为20字符
* [modify] 将用户密码最大长度改为20字符
* [remove] 移除自定义数据项模块
* [remove] 移除用户管理的导入功能按钮
* [bug-1003] 新增时存在xxxx问题                      //对应禅道上的bug号
* [bug] 修改用户时xxxx问题                          //开发人员自己发现的bug

7 开发指导要求

在开发过程，一些处理逻辑和方法，将在此章节进行规范和指导，以及在后续开发过程遇到常见的问题，也都将记录在此，为后续的开发工作提供帮助。

7.1 内容格式化

7.1.1 日期时间

在页面上显示日期时间，要求按照下面格式处理显示

• 日期(Date) : yyyy-MM-dd ,例如2018-05-12
• 时间(DateTime): yyyy-MM-dd HH:mm:ss，例如2018-05-12 05:20:00

如果只显示到分钟或小时，同样按上面格式进行裁剪就即可。

7.1.2 时长格式

在页面上显示时段长时，比如离线时长、在线时长、租赁时长等等，应按如下格式显示

• x年x月x天x小时x分： 最小刻度到分

在此，我们进行举例

• 正确用法： 5月1天1小时5分
• 错误用法： 0年5月1天1小时5分(最前面只有大于0时才显示)

附录

1 常用开发工具包

1.1 JAVA篇

1.1.1 Kafka-starter

1.1.2 Data-Center

1.1.3 CTOUtil

1.1.4 EasyExport

前端篇