gitlab项目代码仓库管理指南（自用）_gitlab代码管理规范

gitlab项目管理流程

注意事项

1. 任何项目开始即创建对应项目仓库；
2. issues应覆盖项目从原始需求->项目结题过程中各环节，记录问题、解决思路等；
3. 及时整理，及时归档；

流程图

git常用命令图

创建项目团队

注意事项

1. 正式项目应所属团队，对于新项目，先创建团队，再创建项目；

建立新团队

• 选择团队Groups -> Explore groups -> Your groups

  创建子团队New Project -> New subgroup

• 直接创建团队 Groups -> Your groups -> New Group

• 填写团队信息

创建项目仓库

注意事项

1. 新建项目时，注意项目名中不要出现中文;
2. 正式项目应所属于项目团队;
3. 项目描述应尽量简洁明了;
4. 内部开发项目的可见性应为Private;

建立项目

通过更改Project slug修改所属团队

• 创建项目New project

• 填写Project name，Project slug与Project description， 在Project URL选择项目团队或个人，在Visibility Level选择项目的可见性。

• 完成空白项目创建。

在子团队下创建项目

• 打开子团队页面
• 创建项目 New Project
• 填写项目信息

编辑项目

• 编辑项目信息Settings -> General

• 删除项目Settings -> General -> Remove -> project -> Confirm

构建项目代码目录

注意事项

1. gitlab作为代码管理仓库，目录应仅包含必要的程序及示例，善用.gitignore进行过滤；
2. 代码目录层级清晰，命名能反映其中内容，例如：src、examples、models、asset(image...）;
3. 在初次保存提交前，应编写好readme.md文件，其中应包含如下内容：
   • 项目名称
   • 项目说明
   • 代码结构说明（可使用tree命令生成代码树）
   • 运行（Quick Start）：包含运行依赖、运行步骤或使用说明
   • Changelog：版本历史说明
   • 其它说明文档（例如：FQA，接口说明，注意事项，错误码说明等）
4. 在需要进行说明的子目录中，添加 readme.md；

.gitignore

• 操作如下：

  # 添加.gitignore至跟踪列表
  git add .gitignore
  # 查看状态，包括忽略的文件
  git status --ignored
  
  # .gitignore没起作用？ 因为忽略的文件已在跟踪列表中，需要先清除
  git rm -r --cached .                    # 清除缓存 -r 表示递归删除（如果有文件夹的话） . 表示所有文件
  
  # 查看一下具体效果
  git status --ignored
  git add .                               # 重新trace file
  git commit -m "update .gitignore"       # 提交和注释
  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12

配置全局git信息

• 安装Git后，打开终端，Ctrl + Alt + T(Linux) 或 Git bash here(Windows)。
• git config --global user.name "Your name"
• git config --global user.email "Your email"
• 通过git config --list查看git全局信息配置

推送项目仓库

方式一: 创建新的项目仓库并推送

• 本地创建新的文件夹，在其路径下克隆.git文件 git clone git@xxx.git
• 创建README文件 touch README.md
• 跟踪新增文件 git add README.md
• 保存修改 git commit -m "add README.md"
• 提交修改至远程仓库 git push -u origin master

方式二: 推送现有的文件

• 切换至现有文件目录 cd existing folder
• 初始化git配置 git init
• 连接远程仓库 git remote add origin git@xxx.git
• 跟踪目录下所有文件 git add .
• 保存修改 git commit -m "Initial commit"
• 提交修改至远程仓库 git push -u origin master

方式三: 推送现有的项目仓库

• 切换至现有项目仓库 cd existing repo
• 初始化git配置 git init
• 连接远程仓库 git remote add origin git@xxx.git
• 提交修改至远程仓库 git push -u origin --all
• 提交版本信息至远程仓库 git push -u origin --tags

利用issues协作开发

注意事项

1. issues应包含项目全周期中遇到的问题和解决的过程;
2. 项目开始即可创建里程碑和issue;
3. 按照项目需要，按照规范创建issues的相关label;

创建里程碑

• 选择Milestones： Issues-> Milestones -> New milestone

  • 填写里程碑信息

创建labels

• 选择labels： Issues-> labels -> New label

• 基础labels: 按照任务所处的阶段大体分为5个基础label

  1. 需求： Demand #0033CC
  2. 设计： Design #69D100
  3. 开发： Develop #8E44AD
  4. 测试： Test #CC0033
  5. 部署： Deploy #AD8D43

• 自定义label: 项目技术负责人可以根据issue的实际内容进行label review， 新建、修改labels，为issue增加labels。一个issue可以有很多标签，当issue较多时便于搜索和管理。

创建issues

• 选择项目，创建issue;

• Issues -> New issue -> 填写issue详情 -> Submit issue

• 可通过建立issue指派任务，并选择时间节点、里程碑和标签信息。项目成员在创建issue后，请在评论区@项目技术负责人，对issue的labels、milestone、Due Date进行确认。

• issue建立后，相关项目人员可在该issue下，通过markdown编辑评论。

代码开发与提交

注意事项

1. 开发人员在开发过程中应将代码提交至自己相关分支下，而不应该提交到master分支下。为保证这点，项目的权限分配就应限制除了项目负责人的开发权限为maintainer外，其他开发成员的权限均为developer。
2. 提交到master分支的代码应进行了充分的测试，确保其可用性。
3. 代码提交前，要先拉取仓库的最新代码，并解决冲突，否则可能会造成混乱。
4. 代码commit时，应使用正确的格式，在commit信息的开头应使用如下标签，使你的提交内容更清晰。

   feature      # 新增功能
   update       # 更新功能
   fix          # 修复漏洞
   delete       # 删除内容
   1
   2
   3
   4

5. 代码commit时，可在commit的内容中添加issue的编号，将issue与commit内容绑定。
6. 若你的项目仓库中需要包含其他的项目仓库，可使用子模块功能。合理使用子模块可以促成代码的分支，提高各项目成员开发效率。

创建开发分支

本地创建开发分支,上传至远端仓库

• 首先需要克隆文件到本地，初始化git配置，连接远程仓库（见第3节）
• 查看本地分支 git branch
• 查看远程分支 git branch -r
• 创建本地分支（不切换） git branch [name]
• 切换本地分支 git checkout [name]
• 创建并切换到本地分支 git checkout -b newbranch
• 删除分支git branch -d [name] （-d选项只能删除已经参与了合并的分支，强制删除请使用-D）
• 将名称为[name]的分支与当前分支合并 git merge [name]
• 创建远程分支(本地分支push到远程) git push origin [name]
• 删除远程分支 git push origin :heads/[name]

issue上创建开发分支

• 在项目的代码开发，应该有相应的issue对应，可以在对应的issue上创建新分支,新建分支名格式:dev-*

• 点击对应issue详情页 -> Create merge request边上下拉按钮

  1. Create merge request and branch: 创建分支并创建合并请求，合并请求信息可以再进行编辑，默认为WIP状态，这种方式创建的分支，在合并完成后会自动关闭该issue；

  2. Create branch: 只创建分支；

gitlab上创建开发分支

• 在指定项目中创建分支： Repository -> Branches -> New branch

• 从远程仓库拉取分支至本地： git pull 或者 git pull origin [name]

代码提交

• 拉取最新代码 git pull，解决冲突（若存在）
• 保存修改 git commit -m "update: information"
• 保存修改并绑定issue git commit -m "fix: #issue_ident_1 #issue_ident_2"
• 提交修改至远程仓库分支 git push origin newbranch
• 提交修改至远程仓库主分支 git push origin master
• 提交修改至远程仓库，同时创建新分支 git push origin newbranch:newbranch

子模块

• 添加子模块git submodule add <仓库地址> <本地路径>
  添加成功后，在父仓库根目录将自动增加.gitmodule文件。

   [submodule "sub"]
   path = lib
   url = ssh://git@xxx/sub/sub.git
  1
  2
  3

  并且在父仓库的git配置文件中加入了submodule段。

   [submodule "sub"]
   url = ssh://git@xxx/sub/sub.git
  1
  2

• 初始化本地配置文件git submodule init
• 子模块更新git submodule update
• 快捷更新子模块git submodule update --init --recursive
• 删除子模块git rm --cached <本地路径>

分支合并

注意事项

1. 若希望确保请求在完工后再合并，开发人员应在merge requests的标题开头加入WIP：记号或者在评论区输入/wip。加入此记号后，除非项目负责人点击了Resolve WIP status，否则请求将无法被合并。
2. 开发人员可以在merge requests的描述中绑定相关issue（如：fix/close #1），支持批量操作。
3. 合并请求的审查与操作应由项目负责人负责，如有异议应及时通知相关开发人员。

开发人员发起合并请求

• 创建合并请求Merge Requests -> Create merge request

项目技术负责人审核代码，进行合并

• 项目技术负责人审查merge requests Todo -> Merge Requests

• 合并分支（如需合并WIP分支，选择Resolve WIP status），点击Merge

• 分支被成功合并

完成里程碑节点

注意事项

1. 当项目完成一个里程碑节点时，应及时使用标签标记。标记的版本必须保证经过了充分测试，能够稳定运行。这一操作通常由测试人员完成。

2. 标签描述应遵循打标规则。通常情况下，描述中必须写清当前的版本号，以及版本更新内容。

3. release版本必须从对应tag标签中输出；

4. 发布版本中需要添加日期信息； VX.Y.Z_YYMMDDhhmmss,例如V1.0.1_20211104

   描述项	说明	必须
   V	版本号起始位	True
   X	初始值为1，主版本号，1位数字	True
   Y	初始值为0，次版本号，1位数字	True
   X	初始值为0，修订号，1位数字	True
   YYMMDD	日期，年月日	False
   hhmmss	可选，24h制	False

   a. 主版本号，一般不变动，除非为全新开发，或完全重构；

   b. 次版本号，比较大的功能修改，后面更新也只针对新版本，的功能性新增；

   c. 修订号，小的修改，bug修复；

标签操作

• 创建本地标签git tag <tagName>
• 为特定提交打标签git tag -a v1.0 [SHA] -m "v1.0: information"
• 推送标签git push origin :<tagName>
• 推送所有标签git push origin --tags
• 查看本地某个标签的详细信息git show <tagName>
• 查看本地所有标签git tag或git tag -l
• 查看远程所有标签git ls-remote --tags origin
• 本地标签删除git tag -d <tagName>
• 远程标签删除git push origin :refs/tags/<tagName>
• 检出标签git checkout -b <branchName> <tagName>
• 切换标签git checkout <tagname>

完成开发后，输出上线版本并备份（待完善）

注意事项

1. 详见Gitlab官方发布的Release API

整理开发相关文档

注意事项

1. 项目结项后，为保证资料的完整性，应及时整理项目资料，并上传项目代码仓库；

2. 对于比较大的文档文件，外网上传至百度网盘公共账号，内网上传至文档云，并在说明文档中提供链接；

3. 按如下内容检测项目文档的完整性：

   • 项目需求相关文档
   • 项目设计相关文档
   • 代码说明文档
   • 部署相关说明文档
   • 运维文档

归档

注意事项

1. 项目结项后，应将代码仓库归档。归档后，该仓库将默认不可见。可以通过在Gitlab修改显示设置浏览归档仓库，或取消归档属性。
2. 归档时，为便于管理，应根据即时人员信息，修改项目成员内容。

项目归档

• 归档Settings -> General -> Archive project

• 查看归档仓库：下拉Last updated选择Show archived projects(only)

• 查看已归档仓库内容（只读）

• 解除归档