使用指引及规范

海信集团目前使用GitLab作为代码仓库，地址为http://gitlab.hisense.com。

注意

为防止代码泄露，要求所有访问者强制在虚拟桌面内访问，所有访问者使用海信统一SSO登陆认证，用户名及密码与LDAP相同。

代码仓库定位

面向软件项目：进行源代码程序的托管。
- 原则上不托管非源码类如：jar\.war\.zip的交付物
- 此类交付物建议项目团队自行管理版本
- 因为此类交付物多数是二进制格式、且文件容量较大，在代码仓库进行版本管理后，占用空间过大。
面向开发人员：进行代码查看、提交、同步管理
面向技术经理：进行代码审查、分支合并管理
面向软件管理人员：代码管理规范性检查
面向信云平台：作为程序包构建的源头

文档中的概念

角色划分

1.GitLab配置管理员：杜艺
2.项目空间管理员：各公司/部门下具体项目的管理员，一般是项目经理或顾问
3.项目管理员：代码交付的负责人，一般是技术经理或交付经理
4.开发工程师：代码交付的开发人员

项目空间(Group)

项目的集合，一个项目空间下可以拥有多个项目。

在项目空间分配的人员权限，会穿透到该空间下所有项目中。

在项目中又对其进行二次权限分配，会以项目中的权限为准。

项目(Project)

项目为Gitlab中的最小管理单元，所有的文件/代码都存放在项目下。

账号申请与登录

操作指导：

1.如果已有Ldap账号，直接登录即可（参看下图），无须申请。
2.如果无Ldap账号，请在koa中发起"ldap信息账号注册"流程进行申请。
3.非海信集团人员如果需要使用Gitlab，同样需要由海信负责人在koa中发起"ldap信息账号注册"流程，申请外部人员账号。

操作规范：

1.【强制】集团Gitlab使用Ldap账号登录（即OA账号）
2.【强制】代码仓库仅能在虚拟桌面中访问使用（参看虚拟桌面使用规范与流程）

使用指引及规范

管理员使用指引及规范

项目空间申请

操作指导：

1.项目空间管理员：在Jira的CM_REQUEST(CMREQ)项目中创建"Git环境申请"流程,并填写相关信息（参看下图）
2.GitLab配置管理员：根据申请内容完成项目空间(git group)的创建
3.GitLab配置管理员：在项目空间(git group)指派项目空间的管理员
4.项目空间管理员：后续在gitlab仓库平台完成项目空间下项目的创建和权限管理

操作规范：

1.【强制】“概要”中，一定要注明：公司名称、部门名称、项目名称 ——定位“项目空间”
2.【强制】明确“项目英文缩写” ——定位“项目”
3.【强制】明确“项目负责人” ——定位“项目空间”管理员

项目的创建

操作指导：

1.由项目空间管理员完成：

  1).项目空间内→new project或new subgroup
  2).空项目：指定project的name，即git仓库的path段
  3).导入项目：填入源项目的仓库地址 与 新项目的名称，导入即可 
      a.注意：源项目非开放的话，需要填入用户名密码，如http://user:password@gitlab.hisense.com/xxx/yyy.git
      b.此方式特别适合从盘古框架导入脚手架，前后端的脚手架地址参看：http://gitlab.hisense.com/Pangea-release

操作规范：

1.【强制】项目的可视范围为 private(默认)

  1).默认从“项目空间”的权限继承
  2).另外两个权限：public是无需登录即可访问、internal是只要登录无需授权即可访问

2.【强制】项目的路径(即project slug)必须是英文

权限设置

操作指导：

1.由项目空间管理员和项目管理员完成：
2.项目空间申请下来后，上述申请中填写的项目负责人会被设置为项目空间的管理员，具有整个空间的管理权限。
```
  1).可以进行空间内子组和项目的创建、修改、删除
  2).可以进行空间内所有的权限分配
```

3.根据项目实际情况，由管理员添加各成员及分配其角色。角色如下：

  1).Owner：只在“项目空间”上分配，可以对“项目空间”和“项目”进行管理
  2).Master：管理员，具备项目修改、权限分配等权限
  3).Developer：开发人员，具备开发相关权限，包括创建分支、提交代码等
  4).Reporter：问题提报人员，具备代码分支的查看权限
  5).Guest：访客，只能看到项目的基本信息，无权浏览代码

4.权限的划分分两个级别：

  1).组的用户权限分配（参考下图1）
  2).项目的用户权限分配。默认继承所属组的权限，重新配置后，覆盖前者（参考下图2）

操作规范

1.【强制】必须遵循“最小权限”原则
2.【强制】开发人员只能拥有Developer角色
3.【强制】不具备任何代码修改权限的人员，只能分配Reporter或Guest权限

代码初始化

操作规范：

1.【强制】项目代码的提交，遵循“源码最小化原则”，即与编译打包不相关的源代码，无需向仓库提交
2.【强制】项目根目录必须包含 .gitignore文件，并按项目的开发语言平台设置合适的忽略内容，可以参看gitignore网站
3.【建议】项目根据开发语言平台，选择合适的包管理工具，以保证仅向仓库提交项目开发的源代码与依赖声明配置文件，而不需要提供依赖的程序包
```
  1).依赖程序包的管理，参看Nexus仓库使用指引及规范（https://confluence.hisense.com/pages/viewpage.action?pageId=16804153)
```

操作指导：

1.由项目管理员完成。
2.项目创建后，可在项目首页看到项目的访问地址（参考下图）：

如果gitlab上已经托管了代码，但本地还未下载，可在本机执行clone命令初始化项目

git clone http://gitlab.hisense.com/xxx.git
cd xxx
touch README.md
git add README.md
git commit -m "add README"
git push -u origin master

如果已经有项目代码，但代码之前并未在Gitlab上管理，可执行以下命令进行初始化

cd existing_folder
git init
git remote add origin http://gitlab.hisense.com/qdxxh/xxx.git
git add .
git commit -m "Initial commit"
git push -u origin master

如果项目代码之前在其他Git仓库进行管理，现在需要迁移到当前项目下，执行以下命令进行初始化

cd existing_repo
git remote rename origin old-origin
git remote add origin http://gitlab.hisense.com/qdxxh/xxx.git
git push -u origin --all
git push -u origin --tags

分支管理(创建&保护)

操作指导：

1.创建分支参看工程师 - 创建分支
2.如果需要对具体的分支进行权限控制，比如master分支只允许管理员进行修改，而不允许普通开发人员修改，则可在Settings -> Repository 中进行配置(如下图)：

操作规范：

1.【强制】任何项目，必须保留master分支，不得删除，并作为测试环境的发布打包分支

  1).在gitlab flow里，对master分支有特殊设定：从其他分支到master做过合并之后，能在分支上显示“merged”标记

2.【强制】上线(部署完成生产环境)的系统，必须创建并保留production分支，不得删除，并作为生产环境的打包发布的分支
```
  1).用于保留生产环境的代码快照
  2).便于进行生产问题的紧急修复
```
3.【强制】上线(部署完成生产环境)的系统，必须同时保护master与production，不得删除，仅由master及以上权限才能对其进行push和merge。
```
  1).目的1：控制程序发布的内容
  2).目的2：通过merge request进行代码审查
```
4.【强制】进入测试阶段后，必须锁定master分支，即developer不可以进行push和merge到master分支。
5.【建议】开发阶段，可以仅保留master，并且开放master分支给developer可以进行push。

合并请求的处理（代码审查）

操作指导：

1.由项目管理员处理，也可以在此进行代码审查。
2.当合并请求被创建后，对应的处理人会在Gitlab中收到通知。
3.点击gitlab到合并通知图标或直接进入merge request管理菜单，即可进行处理合并请求（参考下图）
```
  1).合并前，管理员要认真检查其中commits的changes
```

4.点击“merge”即同意并完成合并

  1).如果发生冲突，此处的“merge”按钮不能点击
  2).需要在线或本地解决冲突后，push合并之后的代码之后，再刷新此页面进行“merge”

5.点击“close merge request” 否决并关闭合并操作规范：
1.【强制】只有在要进行生产版本准备时，发起master分支向production分支的合并请求，即其他时间点不能进行这两个分支的合并
2.【强制】必须在merge request的Discussion中，登记代码审查记录

3.【强制】禁止发起由production分支向任何其他分支的合并请求

  1).因为：如果发生冲突之后，在用gitlab的在线合并功能之后，gitlab会做两个分支的双向合并，参考resolve conflict(https://docs.gitlab.com/ee/user/project/merge_requests/conflicts.html)

4.【建议】完成合并的源分支，建议至少保留一个版本迭代的时间后，再进行删除

合并请求的回滚

操作指导：

1.对合并请求的回滚，请谨慎处理
2.通过对合并请求的回滚，将目标分支（如production的提交）撤销回到合并之前的样子
3.回滚是通过一次新的合并请求完成的
4.所以，“回滚”确认后，会引导到一个“合并请求”的页面，点击“合并”即可，完成的其实是一次“回滚”
5.上述第4步的这次”合并“非常重要，是后续再次合并前，必须要用到的一次合并请求（要对其进行回滚）

操作规范：

1.【强制】回滚时，选择的分支必须是上次合并的目标分支

1).比如，合并时，是master到production，回滚时，选择在production回滚

2.【强制】回滚时，必须选择“Start a new merge request with these changes“
```
  1).不选到话，后续的合并将不能正常发起
```

3.【强制】回滚的合并中，如果源分支内容后续还要继续合并到目标分支到情况：必须先“回滚”上次的”回滚“；并且在此动作之前，不得在目标分支上做任何的合并或提交

  1).比如，撤销了master到production的一次合并；
  2).此时，master的很多修改还是要再次合并到production的；
  3).那么，回到master一定会做修复工作；
  4).修复后，必须先”回滚“刚才那个”回滚master到production的合并“
  5).然后，再发起一次：master到production的合并
  6).不然，只能将c中的修复部分合并到production，其他未修改过的内容，将在两个分支上全部丢失；

tag管理(创建&保护)

操作指导：

1.tag的最佳实践，就是用作标记代码的重要时点，比如版本发布
2.在tag管理界面，进入创建tag的也没
3.创建tag前，选择源分支，一般是发布程序的正式分支，如production分支
4.因为tag标记了代码的重要时点，所以对所有的tag应该进行保护操作规范：

1.【强制】每次合并完成production之后(即发布生产版本)，必须从production创建tag

  1).tag命名规则：v版本号，可用“年月日”作为版本号，如v2020.02.02
  2).tag的机制类似branch
  3).tag的作用是特定时点代码的快照，可以保留各生产版本的完成代码快照，编译回溯与回滚

2.【强制】tag必须进行保护，仅有项目管理员有权进行删改
3.【建议】tag创建时，在Release notes中，对版本升级内容进行登记和描述

工程师使用指引及规范

项目首页:

创建分支

操作指导：

1.可以在服务端创建分支（参考下图1和2，注意到项目中默认会有一个master分支，这个分支不要删除）

2.也可以在本地创建分支，再push到服务端（例如使用idea到task插件，可以根据jira的任务，方便的在本地创建分支）

  1).分支的创建，一定要注意 from的源分支
  2).比如，日程功能开发、bug修复，即from master分支
  3).再比如，紧急的生产问题修复，即from production分支

操作规范：

1.【强制】按迭代计划进行的代码开发，必须在从master分支创建的feature(特性)分支上进行开发
1).分支命名规则：feature-jira任务号-[问题描述]
2.【强制】对生产环境紧急修复的代码开发，必须在从production分支创建的hotfix(紧急修复)分支上进行开发
1).分支命名规则：hotfix-jira任务号-[问题描述]
3.【强制】feature-*分支合并至master分支即可

4.【强制】hotfix-*分支要先合并到production分支，再合并到master分支

  1).一定要注意合并的顺序，因为在gitlab的管理页面上进行merge request管理时，冲突的情况下会出现双向合并
  2).即，先合并到master之后，出现hotfix在合并production生产之前携带着master分支的内容

5. 【强制】禁止在没有任何沟通的情况下，往项目其他成员创建的feature或hotfix分支上进行代码提交

  1).开发类的分支是为解决特定问题创建的，之间的合并一定是对两个分支的情况都了解的背景进行的

创建合并请求

操作指导：

1.由开发工程师完成：
2.如果某分支被设为保护分支后，开发人员是无法直接往该分支上直接推送代码的。
3.这时可以通过提交合并请求方式，申请将已完成代码修改的特性分支合并到该分支上。

4.在合并请求被通过，代码修改的部分即会被同步到该分支上。

  1).发起合并请求前，一定要确认清楚合并的源分支和目标分支正确，以及commits的内容

操作规范：

1.【强制】feature分支，只能发起向master分支的合并请求

2.【强制】hotfix分支，除向production分支发起合并请求外，也必须向master发起合并请求

  1).hotfix向master分支合并的原因是，是为了同步此次紧急修复的内容
  2).同时避免在下次发布生产分支，要进行master到production合并时的冲突

使用指引及规范 ​

代码仓库定位 ​

文档中的概念 ​

角色划分 ​

项目空间(Group) ​

项目(Project) ​

账号申请与登录 ​

使用指引及规范 ​

管理员使用指引及规范 ​

项目空间申请 ​

项目的创建 ​

权限设置 ​

代码初始化 ​

分支管理(创建&保护) ​

合并请求的处理（代码审查） ​

合并请求的回滚 ​

tag管理(创建&保护) ​

工程师使用指引及规范 ​

创建分支 ​

创建合并请求 ​

使用指引及规范

代码仓库定位

文档中的概念

角色划分

项目空间(Group)

项目(Project)

账号申请与登录

使用指引及规范

管理员使用指引及规范

项目空间申请

项目的创建

权限设置

代码初始化

分支管理(创建&保护)

合并请求的处理（代码审查）

合并请求的回滚

tag管理(创建&保护)

工程师使用指引及规范

创建分支

创建合并请求