Hello World in GitLab

简介：最简单的 GitLab 入门实践。
目标对象：初次使用 GitLab 的人群。
演示平台： GitLab 网站。
学习目标：学习 GitLab 的使用方法，了解相关概念。

Git vs GitHub vs GitLab

区分 Git，GitHub，GitLab：

• Git 是一个软件，用于跟踪本地文件修改，并能与远程仓库同步。
• GitHub 和 GitLab 是基于 Git 实现的代码托管云服务平台。
• GitHub 是最大的开源项目代码托管平台。
• GitLab 可以在私有环境部署。

本教程将会学习 GitLab 的使用方法，你可以在学习过程中，了解到 GitLab 是什么，可以做什么。

本教程的操作全部都会在 GitLab 网站上操作，不需要安装应用，十分方便。

Say Hello

在这一章节，我们的目标是通过任务 Say Hello，初步使用 GitLab 的 fork, edit, commit, merge request 等功能。

任务：在项目 Exercises 的 README.md 文件中用 “Hello from No.$ID @$name” 的形式说一句 hello 。

我们提供了一个 GitLab 网站上的项目 Exercises，用于教程任务。

项目简介

点击项目 Exercises 链接，跳转到 GitLab 项目首页 Exercises > Project overview > Details，查看项目的基本信息：

1. 项目名称 Exercises。
2. Branch 分支。“分支”可以理解为项目的快照。如果现在不能理解什么是分支，可以暂时把分支理解为项目的一个快照。一个项目可以有多个分支。一个项目至少有一个分支。master 是项目默认分支“主分支”。
3. GitLab 会把名称为 README 的文件内容展示出来。README.md 的 md 是 Markdown 的缩写。Markdown 是一种轻量级标记语言，可以用纯文本格式编写文档。

点击右上角头像处 Edit Profile，进入页面 User Settings > Profile，查看个人信息(任务中会用到 User ID 和 User Name)：

1. User Name（@符号后的字符串，不包括字符@）
2. User ID
3. Email

项目副本

Fork， 叉子，分叉，复刻。Fork 功能生成一个项目的副本，这样就可以在不影响原始项目的情况下进行更改。

1. 点击 Fork。
2. 点击 Select。选择副本生成位置：个人命名空间下。
3. 查看在网页左上角，这里标注了项目是属于个人的项目副本。

为什么不用 copy 这个词表示生成项目副本？
一个项目可以生成多个副本，就像一个叉子，从手柄部分分出好几个叉子一样。fork 强调原始项目和项目副本之间的关系。

编辑文件

接下来的操作都是在项目副本上进行。

1. 选择 Exercises > Repository > Files > README.md 文件。
2. 点击 Web IDE，进入编辑页面。 Edit 和 Web IDE 都可以编辑文件。以下演示在 Web IDE 页面进行，因为 Web IDE 展示内容更方便。

编辑输入：

Hello from No.$ID @$name

点击 Preview Markdown，查看 Markdown 格式的预览效果。
前面提到：Markdown 是一种轻量级标记语言，可以用纯文本格式编写文档。简单地说，“纯文本格式编写文档”是指我们可以用文本符号表示某种格式，比如一个 # 符号表示一级标题，两个 ## 符号表示二级标题。

点击 Review，检查编辑内容。左侧是原始文件，右侧是编辑后文件。

提交

commit 提交：把本次修改内容，提交到某个分支中。

通常，编辑文件的下一步“保存文件”，但在 Web IDE 上没有“保存”，只有 commit 提交。

1. 点击左侧栏的 Commit。
2. 填写 Commit Message(提交信息)：say hello。Commit message 提交信息描述您对项目做了什么修改，比如增加了什么功能，删除了什么文件，完成了什么任务。
3. 选择 Commit to master branch。注意，此处 master 是指项目副本的主分支，不是原始项目的主分支。
4. 点击下方的 Commit。

返回首页，编辑的内容在首页显示了。

合并分支

目前为止，我们修改的是项目副本，只有您自己能看到修改内容。完成任务后，我们需要申请合并分支 merge request，把修改同步到原始项目。

1. 选择 Exercises > Merge Requests。
2. 点击 New merge request。

1. 选择 source branch（源分支：包含了修改内容的分支）为项目副本的主分支。
2. 选择 target branch（目标分支：希望与源分支合并的分支）为原始项目的主分支。
3. 点击 compare branches and continue（比较分支并继续）。

1. 填写 title 标题，简单描述修改内容：hello from @name。
2. 填写 description 描述，详细描述修改内容：@name says hello。
3. 点击 submit merge request 提交合并请求。

返回原始项目首页，编辑内容没有展示在首页上。
因为 merge request 是合并请求，并不是“合并”。只有经过审核、批准后，才会真正发生合并（权限问题）。

至此，我们已经完成了 say hello 的任务。

Say Hi

回想 Say Hello 教程，Say Hello 需求从何而来？Say Hello 动作看起来像是无缘无故发生的。如果这时修改任务内容为 say Hi。项目没有记录任务经过修改。

任务应从“记录需求”开始。我们需要使用 GitLab 的 issue 功能。

issue: 问题，事务。issue存在的意义，是为了跟踪需求，记录过程。

任务：在项目 Exercises 的 README.md 文件中用 “Hi from No.$ID @$name” 的形式说一句Hi。

创建 issue

新建一个 issue，记录管理员口头说明的需求 say hi。

1. 选择 Exercises > Issues > List。
2. 点击 New Issue。

1. 填写 title 标题: say hi。
2. 填写 description 描述。
3. 点击 submit issue。

issue 带有序号 #1 和 open 状态。

Say Hi

完成 say hi 任务：

1. 编辑文件。请主动犯一个小错误：写一个错误的ID。这个小错误，会在后面的任务中改正。
2. 填写 Commit Message: say hi。
3. 选择 Commit to master branch。
4. 点击 Commit。

关闭 issue

1. 选择 Exercises > Issues > List。
2. 点击 close issue 关闭需求。issue 状态：close。

扩展问题

issue 只描述了任务，并没有要求是您去完成。issue 如何分配给开发者？issue 有没有到期日期？
手动关闭 issue 太麻烦了，能不能 commit 提交时自动关闭对应 issue ？
除了 open/close 状态，issue 能否记录更多状态？比如，doing（正在处理），on hold（等待处理），refuse（拒绝）。
如果 issue 有多个状态，如何更直观地查看多个 issue 和状态？

issue 扩展学习

谁完成需求

issue 只描述了任务，并没有要求是您去完成。issue 如何分配给开发者？issue 有没有到期日期？

1. 选择 Exercises > Issues > List。
2. 点击 Reopen issue 重新打开 issue。
3. 设置 Assignee（接受 issue 任务的人）, due date（到期日期）。

现在issue记录了需求是什么，需求分配给谁（自己），需求的到期日期（今天）。
刷新页面，注意到左上方 to-do-list 数量增加了。

1. 点击左上方 to-do-list。issue 具有 todo/done 状态（区别于 open/close 状态）。
2. #1 say hi 任务已完成，点击右侧 done，改变 issue 状态。
3. 选择 done 列表查看已完成 issue。

commit 关闭 issue

前提：在“issue 扩展-谁在完成需求？”中，issue 已经再次打开，处于 open 状态。如果 issue 是 close 状态，请点击 Reopen issue 再次打开。
手动关闭 issue 太麻烦了，能不能 commit 提交时自动关闭对应 issue ?
刚才写错 ID，现在去改正 ID。

1. 编辑文件，改正 ID。
2. 填写 commit message: close #1。在 commit message 中用关键词 close 和 issue 序号，将会自动关闭相应序号的 issue。
3. 选择 Commit to master branch。
4. 点击 Commit。

1. 查看 Exercises > Issues > List 页面，可以看到 issue #1 已经自动关闭了。
2. 点击 say hi 查看 issue 具体变化。
   最新记录显示 “@Josie close via commit xxxxx 21 minutes ago”：21分钟前，用户 @Josie 通过提交 xxxxx 记录，关闭了 issue。
   通过 commit message 关闭 issue，不仅避免了手动关闭 issue，还把 commit 提交记录与 issue 关联起来了。

label 标签

除了 open/close 状态，issue 能否记录更多状态？比如，doing（正在处理），on hold（等待处理），refuse（拒绝）。

这需要使用 GitLab 的 label 标签功能。

1. 选择 Exercises > Issues > Labels 。
2. 不需要使用默认标签，可以删除：点击右侧 ⋮ ，选择 delete。

1. 选择 Exercises > Issues > Labels 。
2. 点击 new label。
3. 创建一套表示优先级的 label。
   3.1 填写 title。
   3.2 填写 description。
   3.3 选择颜色。
   3.4 点击 create label。

high（高优先级）：对系统有重大影响，只有解决它之后，才能去完成其他任务。
medium（普通优先级）：对系统的某个部分有影响，用户的一部分操作会达不到预期效果。
low（低优先级）：对系统的某个部分有影响，用户几乎感知不到。
trivial（微不足道）：对系统的功能没有影响，通常是视觉效果不理想，比如字体和颜色不满意。

创建 label 的建议：
label title 使用统一的格式，比如小驼峰式：第一个单字以小写字母开始；第二个单字的首字母大写，例如：firstName、lastName。
同一套 label 使用同一种颜色。

给 issue 添加label:

1. 选择 Exercises > Issues > List > #1 say hi。
2. 选择右侧 Labels > Edit，选择 trivial 标签。
3. 返回 Exercises > Issues > List，点击 all，可以看到 #1 的 trivial 标签。

标签一般是一整套的。使用不同的标签，label 可以发挥不同的作用，比如：

1. 快速定位问题类型：错误，新功能请求，建议。
2. 任务状态：等待处理，正在处理。
3. 快速确定涉及应用程序的哪个组件。
4. 优先级。

boards 看板

创建了更多标签之后，怎样直观展示 issue 和 label？
这需要使用 GitLab 的 boards 看板功能。

boards（看板）主要用于项目的进度管理。

依旧通过一个任务来学习新功能：创建2个 issue，分别使用不同的 label。

现在我们先创建两个新标签和两个任务。

1. 创建两个新标签。添加 todo（等待处理）和 doing（正在处理）两个 label。

   标题：todo。描述：等待处理。
   标题：doing。描述：正在处理。

2. 创建2个 issue。issue 可以在创建时选择 label。

   标题：add heading。描述：添加一个六级标题: Comment from @$name 。label: todo, low。
   标题：change format。描述：修改格式：把 say hi 的内容改为代码块的格式。使用符号```。label: todo, medium。

1. 选择 Exercises > Issues > List，查看多个 issue 使用多个 label 的情况。如果我们希望看一下 GitLab 入门学习的整体进度，这张图并不能够一眼看出整体进度，并且有些混乱。
2. 选择 Exercises > Issues > Boards 进入看板页面。按照不同的阶段/状态，看板分为若干列。默认包括 open, close 两列。
3. 点击右上角 Add list，选择 todo, doing，看板添加 todo，doing 列。看板直观展示标签，项目进度更清晰：两个 issue 等待处理，没有正在处理的 issue。

现在有两套标签，一套表示优先级，一套表示进度。boards 看板功能允许创建多个看板，从不同维度查看 issue。

1. 选择 Exercises > Issues > Boards 进入看板页面。
2. 点击右上角的下拉列表，选择 create new board。
3. 创建专门查看优先级的看板。填写 title: Priority（优先级）；取消勾选 show the open list 和 show the closed list。
4. 添加 high, medium, low, trivial 标签列。已经 close 关闭的 issue 不会展示：#1 say hi issue 具有标签 trivial，但没有显示在 trivial 列。

看板有过滤功能。过滤条件包括：issue 的创建者、受托人、里程碑、标签等内容。看板的过滤功能比较简单，只能做相等比较，比如过滤标签，只能筛选等于某个标签或不等于某个标签。 可以使用多个过滤条件。

1. 点击上方的方框，选择 label、等号、标签 medium。
2. 过滤后，只有带有标签 medium 的 issue 会保留。

boards 常用于划分项目周期。按照不同的阶段，看板分为若干列。
常见的划分：
todo, doing, done: 待开发，开发中，已完成
todo，plan，develop，test，deploy，done。（待安排）（计划）（开发）（测试）（部署）（已完成）

milestone 里程碑

boards 看板展示标签、项目进度，侧重过程。怎样算完成 “GitLab 入门”这个目标？
这需要使用 GitLab 的 milestone 里程碑功能。

1. 选择 Exercises > Issues > Milestones，点击 new milestone。
2. 填写 title: GitLab 入门；填写 description: GitLab 实践，熟悉 GitLab 基础使用方法。点击 create milestone 创建里程碑。

里程碑特点1：一般以功能或任务的完成作为 milestone 的目标，而不是以时间段来设置里程碑。

1. 里程碑自带3个划分 issue 的状态：未开始的issue（open状态且未分配），进行中的issue（open状态且已分配），已完成的issue（close状态）。
2. 选择 Exercises > Issues > List > #1 say hi，选择右侧栏 Milestone, 在下拉列表选择 “GitLab 入门”，把 issue #1 放在 “GitLab 入门”里程碑。
3. 返回里程碑页面，可以看到 issue #1 属于已完成的issue（close状态）。
4. 把其他 issue 放进 milestone（操作图：略）

里程碑特点2：里程碑 milestone 是 issue 的容器，相关的 issue 都可以放在一个 milestone 里。

只要完成了这些 issue，GitLab 就算得上“入门”了。目前还有两个 issue 待完成。 ps: 需要把 issue 分配给自己。

1. 选择 Exercises > Issues > Milestones。
2. 在右侧栏选择 start date 和 due date（开始日期和可选的截止日期）。

里程碑特点3：虽然是以功能完成为目标，milestone 具有可选的开始日期和可选的截止日期。但日期不是里程碑的重点。

GitLab 文档： GitLab 中的里程碑是一种跟踪问题和合并请求的方法，这些请求是为了在特定时间段内实现更广泛的目标而创建的。里程碑允许您组织问题并将请求合并到一个有凝聚力的组中，并具有可选的开始日期和可选的截止日期。

这说的就是 milestone 的3个特点：
一般以功能的完成作为 milestone 的目标，而不是以时间段来设置里程碑。
milestone 用作 issue 和 merge request 的容器，相关的 issue 和 merge request 都可以放在一个 milestone 里。
milestone 具有可选的开始日期和可选的截止日期。

小结

分配任务、到期日期、里程碑、标签，都可以在创建 issue 时设置。

Branch 分支

现在，让我们先完成 add-heading 任务，把 issue 从 todo 移动到 doing。

工作中，我们会遇到一些突发情况，比如：您正在添加六级标题，“###### Comment from @ID”的 # 符号只敲了5个（实际需要6个 # 符号），突然，领导让您先暂停手上的工作，先处理修改格式的 issue。可是文件还没修改好，您不想把文件提交到主分支，但也不想失去目前的工作进度，这该怎么办？
这需要用到 GitLab 的分支功能。

1. 编辑文件，添加六级标题（ # 符号只敲了5个）。
2. 选择 create a new branch，分支名称为 add-heading。
3. 默认勾选 start a new merge request。
4. 点击 commit。

1. 点击 change branches。
2. 选择源分支为 add-heading，选择目标分支为项目副本的 master。点击 compare branches and continue。
3. 填写 merge request 的 title：add heading。点击 submit merge request。

返回首页 Exercises > Project overview > Details，可以看到有两个 branch —— 两个快照。 master 分支没有变化。3 add-heading 分支增加了一个五级标题。

Merge Request

draft / WIP

注意到，分支处于可合并状态，即未完成的任务也可以提交 merge request。
创建了分支，新的问题随之出现：如何防止未完成的分支被合并到主分支master？多个分支有矛盾冲突，如何统一？如何决定哪个分支为准？

在填写 merge request 的 title 时，下方提示 "Start the title with Draft: or WIP:"。
draft: 草稿，草案。
WIP: work in progress 工作正在进行中。

点击左上角的 Mark as draft，把 merge request 标记为草稿状态。

标题自动添加了 draft，表示分支是草稿状态。merge 按钮是灰色，无法合并。

conflict

在 master 分支处理另一个任务 change format：

1. 编辑文件。
2. 填写 commit message: change format。
3. 选择 commit to master branch。
4. 点击 commit。

切换到 add-heading 分支处理任务 add heading：

1. 编辑文件。
2. 选择 commit to add-heading branch
3. 点击 commit。

现在，两个任务都处理完了，考虑合并分支 add-heading 到 master。

1. 选择 Exercises > Merge Request > add-heading，点击右上角 Mark as ready 标记分支为完成状态，标题的 Draft: 消失。
2. merge 按钮仍是灰色，无法合并，并提示 “There are merge conflicts” 分支有矛盾冲突。
3. 点击 resolve conflicts 按钮去处理矛盾。

GitLab 展示了分支有矛盾冲突的地方。左侧是源分支的文件，右侧是目标分支的文件。 如果需要保留其中一个分支的内容，直接点击 use ours 或 use theirs。 如果需要保留两者，则点击 edit inline，然后自己编辑。

点击 edit inline，手动处理。

<<<< ... >>>> 中间是两个分支矛盾冲突的文本。==== 等号上下分别是两个分支文本。
删除不需要的内容。注意删除 ===, <<<<, >>>>, README.md 这些提醒矛盾冲突的文本符号。

修改后，点击 commit to source branch。

处理了矛盾冲突，merge request 变为可合并状态。点击 Merge 合并分支。

返回首页，可以看到两个分支合并后的内容：增加了标题，修改了格式。

code review

现在我们希望把项目副本合并到原始项目，不需要再次提出 merge request。因为前面已经提交过一个把项目副本主分支合并到原始项目主分支的合并申请。
合并申请针对的是分支，而不是申请时的内容。
我们无法合并项目副本到原始项目，只能提出申请，因为我们缺乏相应的权限。 在开发实践中，通过合并申请，往往伴随着 code review （代码审查，实际上会检查提交上任何内容，不限于代码），需要检查是否有错误、修改了不可修改的内容。

GitLab 入门总结

更多

如果你希望实践更多，可以跳转:

• Hello World in Git，学习 Git 基础命令行操作和 Git 分支原理。