基本开发规范 on Macula

环境管理

Mon, 01 Jan 0001 00:00:00 +0000

概述

每套系统都需要经过开发、测试、预发等环节才能够上线，所以这里定义一套标准的环境命名规则。

环境命名

环境名称	说明
local	本地环境，默认的开发人员本地的环境
dev	开发环境，用于开发阶段的部署
test	测试环境，开发提测后测试人员进行测试的环境（有时会和dev公共，减少部署）
stg	准生产环境，开发阶段测试完成后需要发版前的回归测试环境，代码与生产一致
pet	压测环境，用于性能测试
prd	生产环境

分支管理

Mon, 01 Jan 0001 00:00:00 +0000

概述

在软件研发的过程中，代码分支管理模型至关重要，直接影响着软件研发交付的效率。行业里存在着多种不同的分支管理模型，如GitFlow、GitHubFlow、GitLabFlow、OneFlow以及AOneFlow(阿里)。

各模型存在不同的优缺点，需要根据研发团队的实际情况进行选择（甚至对分支模型进行适当的变种，以适应团队实际的需要）。以下针对几个常见的模型进行介绍。

分支模型介绍

GitFlow

GitFlow是最早诞生并得到广泛应用的一种工作流程。该模型中存在两种长期分支：master和develop。master中存放对外发布的版本，只有稳定的发布版本才会合并到master中。develop用于日常开发，存放最新的开发版本。同时还存在三种临时分支：feature, hotfix, release:

feature分支是为了开发某个特定功能，从develop分支中切出，开发完成后合并到develop分支中
hotfix分支是修复发布后发现的Bug的分支，从master分支中切出，修补完成后再合并到master和develop分支
release分支指发布稳定版本前使用的预发布分支，从develop分支中切出，预发布完成后，合并到develop和master分支中

整体分支模型，如下图所示：

优点：

feature 分支使开发代码隔离，可以独立的完成开发、构建、测试
feature 分支开发周期长于release时，可避免未完成的feature进入生产环境

缺点：

无法支持持续发布
过于复杂的分支管理，加重了开发者的负担，使开发者不能专注开发

GitHubFlow

GitHubFlow分支模型只存在一个master主分支，日常开发都合并至master，永远保持其为最新的代码且随时可发布的。在需要添加或修改代码时，基于master创建分支，提交修改。创建Pull Request，所有人讨论和审查你的代码。然后部署到生产环境中进行验证。待验证通过后合并到master分支中。

Macula采用该分支管理模型。

整体分支模型，如下图所示：

优点：轻便快捷、简洁易理解，将master作为核心的分支，代码更新持续集成至master上

缺点：多版本并行的产品线不适用

GitLabFlow

GitLabFlow是GitFlow和GitHubFlow的结合体，吸取了两者的优点：既有适应不同开发环境的弹性，又有单一主分支的简单和便利。该模型采取上游优先的原则，即只存在一个master主分支，它是所有分支的上游。只有上游分支采纳的变动才能应用到其他分支。对于持续发布的项目，建议在master之外再建立对应的环境分支，如预生产环境pre-production，生产环境production。对于版本发布的项目，建议基于master创建稳定版本对应的分支，如stable-1，stable-2。

整体分支模型，如下图所示：

优点：git提交历史更加清晰、简洁与易读

缺点：对开发人员的能力提出了更高的要求，当存在多产品线时，分支管理比较复杂

OneFlow

Adam Ruka 于2017年提出，可以简单的理解为 Git Flow 的简化版本，除了 develop 开发分支和最新发布 master 分支，其余皆是临时分支，一旦开发完成即可删除临时分支。

整体分支模型，如下图所示：

优点：单一版本首选，git 提交历史简介清晰易读

缺点：不适合持续交付或持续部署的项目，也不适用多版本共存的项目

AOneflow

由阿里巴巴技术专家林帆提出的一种改进模型，其主要分为三种分支类型：主干分支、特性分支以及发布分支，并且提出了三个基本准则：

主干创建特性分支，且不允许合并回主干分支
合并特性分支，形成发布分支
发布到线上正式环境后，合并相应的发布分支到主干，在主干添加标签，同时删除该发布分支关联的特性分支

整体分支模型，如下图所示：

版本管理

Mon, 01 Jan 0001 00:00:00 +0000

概述

在软件管理的领域里存在着被称作“依赖地狱”的死亡之谷，系统规模越大，加入的包越多，你就越有可能在未来的某一天发现自己已深陷绝望之中。在依赖高的系统中发布新版本包可能很快会成为噩梦。如果依赖关系过高，可能面临版本控制被锁死的风险（必须对每一个依赖包改版才能完成某次升级）。而如果依赖关系过于松散，又将无法避免版本的混乱（假设兼容于未来的多个版本已超出了合理数量）。

当你项目的进展因为版本依赖被锁死或版本混乱变得不够简便和可靠，就意味着你正处于依赖地狱之中。作为这个问题的解决方案之一，我提议用一组简单的规则及条件来约束版本号的配置和增长。这些规则是根据（但不局限于）已经被各种封闭、开放源码软件所广泛使用的惯例所设计。

为了让这套理论运作，你必须先有定义好的公共 API。这可能包括文档或代码的强制要求。无论如何，这套 API 的清楚明了是十分重要的。一旦你定义了公共 API，你就可以透过修改相应的版本号来向大家说明你的修改。考虑使用这样的版本号格式：X.Y.Z（主版本号.次版本号.修订号）修复问题但不影响 API 时，递增修订号；API 保持向下兼容的新增及修改时，递增次版本号；进行不向下兼容的修改时，递增主版本号。

我称这套系统为“语义化的版本控制”，在这套约定下，版本号及其更新方式包含了相邻版本间的底层代码和修改内容的信息。

版本格式

主版本号.次版本号.修订号

版本号递增规则

主版本号：当你做了不兼容的 API 修改
次版本号：当你做了向下兼容的功能性新增
修订号：当你做了向下兼容的问题修正
先行版本号及版本编译信息可以加到“主版本号.次版本号.修订号”的后面，作为延伸

语义化版本控制规范

以下关键词 MUST、MUST NOT、REQUIRED、SHALL、SHALL NOT、SHOULD、SHOULD NOT、 RECOMMENDED、MAY、OPTIONAL 依照 RFC 2119 的叙述解读。

1）使用语义化版本控制的软件必须（MUST）定义公共 API。该 API 可以在代码中被定义或出现于严谨的文档内。无论何种形式都应该力求精确且完整。

2）标准的版本号必须（MUST）采用 X.Y.Z 的格式，其中 X、Y 和 Z 为非负的整数，且禁止（MUST NOT）在数字前方补零。X 是主版本号、Y 是次版本号、而 Z 为修订号。每个元素必须（MUST）以数值来递增。

 例如：1.9.1 -> 1.10.0 -> 1.11.0。

3）标记版本号的软件发行后，禁止（MUST NOT）改变该版本软件的内容。任何修改都必须（MUST）以新版本发行。

4）主版本号为零（0.y.z）的软件处于开发初始阶段，一切都可能随时被改变。这样的公共 API 不应该被视为稳定版。

5）1.0.0 的版本号用于界定公共 API 的形成。这一版本之后所有的版本号更新都基于公共 API 及其修改内容。

6）修订号 Z（x.y.Z | x > 0）必须（MUST）在只做了向下兼容的修正时才递增。这里的修正指的是针对不正确结果而进行的内部修改。