网站项目 Git 使用流程和规范

零、前言

本文档适用于需要持续发布的网站项目（后端、前端），稍加修改可以适用于需要同时存在不同版本的项目（框架、组件、app 等）。
该工作流程基于 git flow 分支策略，该策略的优点是分支清晰，能够应付开发流程中的许多情况，缺点是分支较多，开发过程中会经常需要进行合并操作，于是在基于该策略的基础上做适当的简化，并考虑并行迭代的情况，综合制定了该工作流程。

本文档共包含分支策略、工作流程、分支使用规范、代码提交规范四个部分，分支策略主要是对 git flow 的介绍，工作流程部分则描述在具体开发过程中该如何实施，分支使用规范详细描述每种分支的用法，最后的代码提交规范是成功推进代码审查的关键因素。

1、术语说明

持续集成/CI：使用该术语一般指 feature 分支的代码频繁集成到 develop 分支，并由 CI 自动构建到测试环境，feature 集成到 develop 一天内最少一次。

持续集成环境：根据特定分支配置的自动构建、运行测试和部署测试程序的环境。

预发布环境：接近生产的环境，而非测试环境。

一、分支策略

1、分支策略

主要分支策略基于 git flow，但基于复杂多变的项目研发过程会有所不同。

Git flow 主要流程见下图，具体使用可参考：http://www.ruanyifeng.com/blog/2012/07/git.html

2、长期分支

master：用于存放对外发布的版本，任何时候在这个分支拿到的都是稳定的版本。

develop：用于日常的开发，存放最新的开发版本。

3、临时分支

feature：用于开发特定功能从 develop 中分出来的，一个 feature 分支对应一次迭代开发，开发完成后合并到 develop 分支中；

hotfix：用于修复 bug，从 master 中分出来的，开发完成后合并到 master、deveop 分支。

release：指发布正式版本之前（即合并到 Master 分支之前），我们可能需要有一个预发布的版本进行测试。

二、工作流程

注：以下文字中粗体为特殊情况，大多数时候不需考虑，从流程中去除的话，该工作流程并不复杂。

1、项目初始

gitlab 上创建项目

创建 develop 分支，并将其设置为保护性分支，具有 Maintainer 权限的用户才可以直接 push 和 merge，其他用户需要将代码提交到自己的分支后发起 merge request（以下简称 MR）请求，由 Maintainer 和团队成员进行代码评审决定是否接受合并。

修改 master 分支为不允许任何人推送，该分支只能通过 MR 进行变更。

2、迭代开始阶段

情况 1：迭代时间较长、分工明确

开发人员各自新建属于自己的 feature 分支，代码持续集成到 develop。

情况 2：迭代时间较短、分工不明确或需要多个人开发同一功能

开发人员共享一个 feature 分支，代码持续集成到 develop。

情况 3：迭代 A、迭代 B 同时启动，A 为主要迭代

主要迭代根据情况 1、2 选择开发方式，代码持续集成到 develop

次要迭代从 develop 分出 sprint-{版本}，feature 基于该版本开发，代码持续集成到 sprint-{版本}

情况 4：主要迭代 A 已启动，突然启动迭代 B

迭代 B 从 master 分出 sprint-{版本}，feature 基于该版本开发，代码持续集成到 sprint-{版本}

注意：情况 2、3、4 均为特殊情况，应尽量避免，尤其是 3、4 两种情况需要将代码持续集成到另一个版本，那么需要配置另一套持续集成环境，同时也加大了代码评审、分支合并的麻烦。下面描述的开发阶段以情况 1 为准，若为 3、4 情况，则需要将 develop 分支替换为 sprint 分支。

3、迭代开发阶段

开发人员完成 feature 的开发或阶段性开发时，发起到 develop 的 MR。

Maintainer 和团队成员对 MR 进行 review，拒绝的需要提交者重新修改代码后再次提交 MR，接受的将合并到 develop，并自动构建到测试环境。

迭代整体测试通过后进入发布准备阶段。

4、发布准备阶段

对于无预发布环境的项目，跳过准备阶段，进入发布阶段。

对于有预发布环境的项目，从 develop 中新建 release 为保护性分支（若已有则合并，该分支可在部署稳定后删除）。

release 分支构建到预发布环境进行测试，若存在 bug，在该分支上进行修改。

完成 release 分支的测试后，进入发布阶段。

5、发布阶段

提交发布申请，运维审核通过后进行代码合并

存在 release 时，release 分支合并到 develop 和 master，不存在时，develop 合并到 master。

通过 master 构建并发布到生产环境。

在 master 上打上版本 tag 标签，标记发布。

6、线上发布回滚情况

出现发布回滚情况时，合并到 master 上的代码也需进行回滚操作。

7、线上 bug 修复

从 master 新建 hotfix 分支用于修复 bug。

完成后将 hotfix 合并到 develop 进行测试。

测试通过后合并到 master 进行发布，并打上小版本号的 tag 标签。

若当前存在 release 分支，还需将 hotfix 合并到 release。

删除 hotfix 分支。

三、使用规范

1、临时分支命名规范

临时分支	前缀	备注
feature	feature-	若 gitlab 中包含任务 issue，可以采用 feature-{issueid}-{简单描述}命名
release	release-	以版本名称或版本号结尾
hotfix	hotfix-	若 gitlab 中包含 bug issue，可以采用 feature-{issueid}-{简单描述}命名
sprint	sprint-	以迭代名称或版本号结尾

CI 管道可通过前缀匹配进行相关的自动化操作。

分支前缀，一般用-/连接，很少用*，*表示两个词语有关联，feature 分支这里实际上是一种分组，所以一般用-/，可以在前缀之后使用_。

2、feature 分支使用规范

分支粒度：以一个功能为单位，尽量对应 gitlab 上的一个任务 issue，开发下一个功能时新建 feature

存在时间：尽量短，合并到 develop 后选择合适的时间点删除 feature

集成频率：每天最少一次，feature 要经常合并到 develop 中，便于 code review，开发要经常从 develop 中获取最新代码；

合并请求：当 feature 完成的时候即可发起 MR，但当一个 feature 开发时间较长时，也应当尽量提早发起 MR，此时可在 MR 中添加 WIP 前缀，表示当前工作正在处理中，相关人员可以提前审核，但不合并

3、hotfix 分支使用规范

与 feature 鉴别：线上除紧急 bug 修复，当需要做功能性调整并快速上线时，也需要新建 hotfix 分支，而非 feature。

4、sprint 分支使用规范

sprint 的使用与 develop 相同，也为保护性分支。

需要从 sprint 中分出 feature 分支进行开发，从 feature 提交 MR 到 sprint 中做代码审查。

5、release 分支使用规范

release 为保护性分支。

使用 hotfix 分支进行 bug 修复。

四、代码提交规范

先说说为什么要制定代码提交规范。

Git 是当前最流行的代码仓管理系统，可以说是开发者的必备技能。它非常强大，使用得当的话可以大幅助力个人效能的提升。如果一个团队的成员都能熟练使用 Git 的话，可以大大提高团队代码的模块化、可读性、可维护性，从而提高团队的研发效能。
成功推进代码审查的两个关键操作：一是注意审查提交的原子性，二是审查中关注提交说明（Commit Message）。

1、代码提交原子性规范

代码提交的原子性，是指一个提交包含一个不可分割的特性、修复或者优化，同时这个提交要尽可能小。如果用一个提交完成一个功能，这个提交还是会比较大的话，我们需要把这个功能再拆分为子功能。

原子性提交的优点：

可以让代码结构更清晰、更容易理解；
出了问题之后方便定位，并可以针对性地对问题提交进行“回滚”；
在功能开关的协助下，可以让开发者尽快把代码推送到 develop/master 上进行合并。这正是持续集成的基础。

规范要求：

一个提交包含一个不可分割的特性、修复或者优化，同时这个提交要尽可能小。

代码审查标准

不符合原子性提交的代码可以直接打回。
逐步要求提交的原子性，不要求一次性到位，但必须逐步改进。

2、代码提交说明规范

好的提交说明可以提升代码可读性，同时也是提高代码审查效率的利器。通过制定严格的提交说明格式来规范其质量，可以方便审查者查理解被审查代码的意图、实现思路，并通过测试情况，加快对代码的理解，提高对代码质量的信心，从而大大提高审查者的效率。同时，严格的提交说明格式及好的说明质量也可以督促开发者提高代码质量。

好的格式应该包含以下几个方面：

标题，简明扼要地描述这个提交。这部分最好在 70 个字符之内，以确保在单行显示的时候能够显示完整。比如，在命令行常用的 git log –oneline 输出结果要能显示完全。
详细描述，包括提交的目的、选择这个方法的原因，以及实现细节的总结性描述。这三个方面的内容最能帮助审查者阅读代码。
测试情况，描述的是你对这个提交做了什么样的测试验证，具体包括正常情况的输出、错误情况的输出，以及性能、安全等方面的专项测试结果。这部分内容，可以增加审查者对提交代码的了解程度以及信心。
与其他工具和系统相关的信息，比如相关任务 ID、相关的冲刺（sprint，也可翻译为“迭代”）链接。这些信息对工具的网状互联提供基础信息，非常重要。