telecom-rd-project-template/.agents/skills/telecom-rd-standards/references/source-documents/08-code-management.md

# 中国电信软件研发规范代码管理分册（修订版）

> 脱敏整理版：已移除编制人员、联系人和联系方式，并合并无意义硬换行。技术条款、章节和示例以原始 DOCX 为争议核验依据。

中国电信软件研发规范代码管理分册 （修订版）

中国电信集团有限公司

## 2023 年 12 月

i

> 编制人员信息已移除。

版本变更历史

## 1 文档说明

### 1.1 编制说明

为进一步提升全集团的代码管理水平，实现代码分级分类管理，集团编制了软件研发规范--代码管理分册， 用于指导和规范全集团使用代码仓库管理代码，规范代码开发过程， 提升代码质量。

### 1.2 文档结构

本规范由文档说明 、代码仓库设置 、分支设置 、开发人员操作规范和代码版本管理等部分构成， 各章节的主要内容如下：第 1 章文档说明， 对编制目的 、文档结构 、使用范围 、起草单位 、解释权、版权和本规范用到的术语进行了说明。第 2 章代码仓库设置，对代码管理工具、代码仓库命名规范、代码仓库必要文件 、代码仓库划分 、仓库大小和权限设置相关要求进行了说明。第 3 章分支设置，对必要分支、git flow工作流分支、代码评审相关要求进行了说明。第 4 章开发人员操作规范，对用户信息设置、代码提交规范、代码文件约束等相关要求进行了说明。第 5 章代码版本管理，对版本号管理、版本号格式、版本描述信息相关要求进行了说明。

### 1.3 适用范围

本规范适用于指导中国电信软件研发工作。

### 1.4 起草单位

本规范的起草单位是中国电信集团公司。

### 1.5 解释权

本规范解释权属于中国电信集团公司。

### 1.6 版权

本规范的版权属于中国电信集团公司。

### 1.7 名词解释

## 2 代码仓库设置

### 2.1 管理工具 （C1）

项目组必须使用 git 管理代码 。代码管理须满足《中国电信代码安全管理实施指引(试行)》相关要求。

### 2.2 命名规范

#### 2.2.1 代码仓库命名 （C1）

代码仓库名称是同一项目/子项目下代码仓库的唯一标识， 代码仓库名称在代码仓库创建之后无法修改，为便于识别，代码仓库名称必须能明确体现代码所属模块或微服务。代码仓库命名规则如下：l 代码仓库名仅使用英文大小写字母（A-Z 、a-z） 、数字（0-9） 、 中划线（-）u 不使用下划线（ _）u 不使用特殊字符l 代码仓库名第一个字符仅使用字母u 首字符不使用数字l 项目内全部代码仓库的命名规则必须要保持规则一致性， 例如： 全部为驼峰模式/全大写字母/全小写字母

#### 2.2.2 代码仓库描述 （C1）

代码仓库描述是声明代码仓库用途的描述信息，使用简洁明了的文字进行描述。l 代码仓库简要描述不得超过 80 字符。

l 代码仓库描述应包含代码仓库所属项目的项目编号 、项目名称和子项目名称。

### 2.3 代码仓库必要文件 （C1）

l 每个项目都需要README.md 文件， README.md 文件中需要包含工程的基本介绍， 工程结构的概要说明及工程文档的存放地址或者链接。l 除文档说明类型仓库， 所有代码仓库都必须包含.gitignore 文件， 放在代码仓库的根文件夹中， 控制 git 仓库排除跟踪的文件。

### 2.4 代码仓库划分

代码仓库是中国电信研发项目的重要数字资产，应对代码仓库进行拆分，避免无关人员访问代码仓库 。 同时， 代码仓库是 devops 流程的基础， 为使 devops流程顺利进行， 也应对代码仓库进行拆分：l 安全管控： 核心代码和非核心代码分库管理， 应严格控制访问核心代码的人员， 避免核心代码泄露 。（C1）l 技术栈： 每个代码仓库仅使用一种技术栈， 如 java maven 、Python 、go、 node.js 等 。（C1）l 微服务： 每个代码仓库不超过 5 个微服务 。（C0）

### 2.5 仓库大小 （C1）

l 原则上， 每个代码仓库不超过 1G。

### 2.6 权限设置

#### 2.6.1 用户角色

代码仓库需要设置仓库管理员（C1） 、分支开发人员（C1） 、分支管理员（C0） 、分支评审人员（C0） 、分支只读人员（C0） 五种角色， 角色权限说明如下表：

#### 2.6.2 权限管控要求

l 仅项目/子项目负责人或项目/子项目管理员具有创建代码仓库的权限。 （C1）l 权限设置必须遵循权限最小化原则， 根据项目需求设定项目组开发人员访问指定代码仓库和具体分支， 分配用户角色， 避免开发人员越权使用代码仓库 。（C1）l 在人员离职 、离开团队的情况下， 必须收回代码仓库权限 。（C1）l 每个代码仓库， 代码仓库管理员不超过 3 人 。（C1）l 禁止设置外协开发人员为代码仓库管理员 。（C1）l 代码仓库管理员应定期梳理代码仓库的权限分配情况， 并及时对权限进行合理调整， 保证权限最小化原则 。（C0）l 严格控制master 和 develop 分支的写权限， 仅允许项目负责人 、小组长等人员推送代码到远程平台代码仓库的master 和 develop 分支 。（C0）l 远程仓库，普通分支由仓库管理员来创建，开发人员只能创建个人分支。 （C0）

## 3 分支设置

远程平台代码仓库是开发人员协同开发的交互中心，应规范设置远程平台代码仓库的分支。

### 3.1 必要分支 （C1）

代码仓库必须具有主干分支（master） 。

### 3.2 git flow 工作流分支 （C0）

代码仓库的默认分支必须为固定分支，不允许把临时分支设为代码仓库的默认分支。

#### 3.2.1 固定分支

代码仓库的固定分支包括主干分支（master） 和开发分支（develop） 。

主干分支 （master）用于存放对外稳定的发布版本，代码库有且只有一个主干分支，作为代码库的基线版本， 同时用来发布生产 tag 版本。master 分支仅允许团队专家访问，不允许普通开发人员直接对master 分支代码进行修改和提交，普通开发人员若要合入代码到master 分支，必须发起合并请求（merge request）， 由 master 角色人员进行评审后合入。master 分支在每次生产版本发布后， 必须打上 tag。

开发分支 （develop）所有最终完成的开发任务，相应的代码都要合并到此分支。此分支上应包含全部最新特性，可以随时发布可测试的（指能编译通过的、部署后可运行起来的，具备测试条件的） 版本。

#### 3.2.2 临时分支

代码仓库的临时分支包括紧急修复分支（hotfix-*）、集成测试分支（release-*）和功能分支（feature-*） 。l 同一代码仓库下的全部分支的命名方式要保持仓库内规则一致性， 全部为驼峰模式/全大写字母/全小写字母l 一项目/子项目下的全部代码仓库的分支命名规则也需保持一致性

紧急修复分支 （hotfix-*）软件正式发布以后，出现需要紧急修复的 bug，以发布的 TAG（master 分支）为基础创建 hotfix分支，进行 bug 修补，验证后将相关提交合并入master 分支和develop 分支。集成测试分支 （release-*）该分支以 develop 分支为基础创建， 在一个的迭代计划的功能开发完成时，把 develop 分支提交合入到 release 分支做集成测试，测试出的 bug 在 release 分支上进行修复， 验收通过后， 提交合并入 master 和 develop。特性功能分支 （feature-*）该分支是开发人员为了开发某种功能， 以 develop 分支为基础创建， 开发完成后， 将相关提交合并入 develop 分支， 完成后删除该分支。

### 3.3 代码评审 （C3）

开发人员的提交必须经过代码评审，可选择单分支代码评审（code review）和多分支代码评审（merge request） 二种评审模式中的任意一种或同时使用二种。

#### 3.3.1 单分支代码评审 （code review）

对于启用代码评审流程的分支， 开发人员推送代码到远程平台代码仓库时，每个提交均需走评审流程， 可结合流水线对代码进行代码安全扫描并返回评分，评审人员对代码进行评审。代码安全评分且人工评审通过的提交合入远程平台代码仓库， 保障代码质量。开发人员推送代码后，在评审人员合入之前，其他开发人员无法拉取本次提交的代码。

#### 3.3.2 多分支代码评审 （merge request）

合并请求可以实现同一个代码仓库不同分支之间在线合并代码，当前分支人员向目标分支发起合并请求，由目标分支管理员或仓库管理员评审后合入代码到目标分支 。使用场景如下：l 特性分支开发人员向开发分支发起合并请求merge request， 由开发分支管理人员或仓库管理员合入。l 开发分支开发人员向集成测试分支起合并请求merge request， 由集成测试分支管理人员或仓库管理员合入。l 集成测试分支测试人员向主干分支和开发分支发起合并请求 merge request， 由主干分支管理员和开发分支管理员或仓库管理员合入。l 修复分支开发人员向主干分支和开发分支发起合并请求merge request，由主干分支管理员和开发分支管理员或仓库管理员合入。

## 4 开发人员操作规范

### 4.1 用户信息设置 （C1）

l 用户信息设置是代码提交的身份验证信息以及度量统计数据的账号信息，须与远端仓库账号 、邮箱保持一致。用户信息设置示例：git config --global user.name zhangsan git config --global user.name [邮箱已脱敏]l 用户密码须不少于 8 位， 且包含数字 、大小写字母及特殊符号。

### 4.2 代码提交规范

#### 4.2.1 commit 的产生 （C1）

l 保持清晰的 commit 历史， 保证每次 commit 操作都是有意义的。l 推送 commit 到远程平台代码仓库之前必须对本地 commit 进行精简合并。原则上， 一个任务不能推送超过 5 个 commit 到远程平台代码仓库。

#### 4.2.2 commit message 规范 （C3）

提交代码应与迭代开发任务关联，代码提交的 commit message 用以关联迭代开发任务或者需求， commit message 须遵循以下格式：type（scope） : subject%workItemId注意格式中的空格及符号l workItemId（可选）： 工作项 ID 数字部分， 以%号开头， 空格结尾 。可放置于提交日志中的任何位置 。可支持多个 ID 串联， 以%号间隔。如： %workItemId1%workItemId2 l type（必选）： commit 的类别， 可使用以下标识：

u feat : 新功能u fix : 修复 bug u docs : 文档改变u style : 代码格式改变u refactor : 某个已有功能重构u perf : 性能优化u test : 增加测试u build : 改变了 build 工具 如 grunt 换成了 npm u revert : 撤销上一次的 commit u chore : 构建过程或辅助工具的变动l scope（可选）： 用于说明 commit 影响的范围， 比如数据层 、控制层、视图层等等， 视项目不同而不同。l subject（必选）： commit 的简短描述commit 示例：%1011 fix（core） : set a to b

### 4.3 代码文件约束 （C0）

提交到代码仓库的文件约束要求如下：l 提交到代码仓库的文件不允许出现数据库账号 、密码等敏感信息。l 不允许提交与项目代码无关的二进制文件。l 提交到代码仓库的单个文件不超过 10M。l 代码的第三方依赖包必须引用制品库的， 不允许把依赖包直接放到代码仓库， 特别是开源项目， 例如 Android 系统。l 不允许提交 pdf/doc/ppt/docx/pptx/xls/xlsx 或压缩包 、音视频等类型文件。

## 5 代码版本管理

代码版本号（Tag） 是代码仓库的一个标记， 是指向某个提交（commit） 的指针， 用于发布版本的管理。

### 5.1 版本号管理 （C1）

发布代码版本时，必须为发布版本的提交打上版本号（tag） ，流水线编译构建生成制品时， 使用代码版本号作为制品的版本号。对于代码配置文件中有版本定义（version） 的， 版本号（tag）必须与配置文件中的版本号（version）保持一致。

### 5.2 版本号格式 （C2）

版本发布时，版本号必须符合版本格式：X.Y.Z（主版本号.次版本号.修订号）。版本号递增规则如下：l 主版本号： 当做了不兼容的 API 修改， 或者大的版本发布；l 次版本号： 当做了向下兼容的功能性新增；l 修订号： 当做了向下兼容的问题修正。如有需要， 先行版本号及版本编译信息可以加到“主版本号.次版本号.修订号 ”的后面， 作为延伸。例子：l 1.0.0-alpha， 1.0.0-beta l 1.0.0-alpha+001 、1.0.0+20130313144700 、1.0.0-beta+sha.5114f85

### 5.3 版本描述信息

版本描述信息应包括迭代任务的工作项 ID 及其描述信息， 详细描述本次迭代版本解决的需求和缺陷。

#### 5.3.1 标签信息 （C3）

标签信息（Tag Message）是管理维度的要求，用于维护版本基线，记录版本日期 、说明信息等。

#### 5.3.2 版本说明 （C3）

版本说明（Release Notes） 是业务维度的要求， 记录本次 Tag 中具体包含的版本内容， 包括： feature 新功能 、fixed 修复内容， 关联的任务 、需求等信息。