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

gitlab项目管理流程

注意事项

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

流程图

workflow.png

git常用命令图

git_commands.png

创建项目团队

注意事项

  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"       # 提交和注释

配置全局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 [email protected]
  • 创建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 [email protected]
  • 跟踪目录下所有文件 git add .
  • 保存修改 git commit -m "Initial commit"
  • 提交修改至远程仓库 git push -u origin master
方式三: 推送现有的项目仓库
  • 切换至现有项目仓库 cd existing repo
  • 初始化git配置 git init
  • 连接远程仓库 git remote add origin [email protected]
  • 提交修改至远程仓库 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. 代码commit时，可在commit的内容中添加issue的编号，将issue与commit内容绑定。
  2. 若你的项目仓库中需要包含其他的项目仓库，可使用子模块功能。合理使用子模块可以促成代码的分支，提高各项目成员开发效率。

创建开发分支

本地创建开发分支,上传至远端仓库
  • 首先需要克隆文件到本地，初始化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

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

     [submodule "sub"]
 url = ssh://git@xxx/sub/sub.git
  • 初始化本地配置文件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. 上传至百度网盘公共账号，内网上传至文档云，并在说明文档中提供链接；

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

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

归档

注意事项

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

项目归档

  • 归档Settings -> General -> Archive project
  • 查看归档仓库：下拉Last updated选择Show archived projects(only)
  • 查看已归档仓库内容（只读）
  • 解除归档