---

一、版本控制的核心原则 🧭

1. 主分支（main / master）仅用于发布稳定版本，不用于日常开发。

   主分支始终保持可部署状态，确保版本稳定、可追溯。

2. 所有功能开发必须在独立分支上完成。

   每项功能、修复或改动应创建独立分支，避免协作冲突，提升开发效率与可维护性。

3. 每次提交都应具备明确目的与描述。

   保持提交记录清晰、结构化，便于代码审查、问题回溯和历史审计。

4. 每次正式发布必须打 Tag，并提供详细的变更说明（Changelog）。

   Tag 应遵循语义化版本控制（如 v1.2.3），变更说明需涵盖新增、优化、修复等内容。

5. 严禁直接向主分支推送代码，所有更改必须通过合并请求（Pull Request / Merge Request）提交。

   所有合并操作需经由代码审核流程，确保团队协作质量与一致性。

二、分支策略（Branch Strategy） 🌿

2.1 分支类型与命名规范

分支类型	命名规则	示例	说明
主分支	main 或 master	master	生产部署分支，仅用于发布版本和打 Tag，不参与开发
开发分支	develop	develop	日常开发集成分支，所有功能分支合并归此，保持阶段性稳定
功能分支	feature/<模块>-<功能>-<任务ID>	feature/user-login-1234	单个功能开发分支，从 develop 创建，开发完成后合并回 develop
修复分支	bugfix/<模块>-<简要描述>	bugfix/userlist-null-pointer	非紧急的缺陷修复，从 develop 创建，修复后合并回 develop
热修复分支	hotfix/<简要描述>	hotfix/fix-prod-login	生产环境紧急修复，从 master 创建，修复后合并回 master 和 develop
发布准备分支	release/v<版本号>	release/v2.0.0	发布前版本封版处理，如补充文档、调整配置等，从 develop 创建，合并回 master 和 develop
测试分支	test	test	用于部署测试环境，合并开发分支后测试用
灰度分支	gray	gray	用于灰度部署或内部试运行，通常从 release 或 master 派生

2.2 可视化流程图

feature/* ─┬─→ develop ─┬─→ test ─┬─→ release ─┬─→ gray ─→ master
           │            │         │             │
           └────────────┘         └── hotfix ───┘

三、提交信息规范（Commit Message）✍️

3.1 提交格式

<type>: <subject>

// 示例
feat: 添加用户登录接口
fix: 修复订单状态不更新的问题

3.2 Type 类型说明

类型	说明
feat	新增功能（Feature）
fix	修复 Bug（Bug Fix）
docs	文档变更（例如 README、说明文档）
style	代码格式调整（空格、缩进、逗号等，不影响功能）
refactor	代码重构（既不新增功能也不修复 Bug）
perf	性能优化
test	添加或修改测试代码
chore	杂项更新（构建脚本、依赖管理、工具配置等）
revert	回滚，撤销之前的提交
build	与构建系统或外部依赖相关的更改
ci	持续集成/持续部署（CI/CD）配置文件修改

四、Tag 版本规范（Tag Strategy）🔖

4.1 命名格式

Tag 命名遵循语义化版本控制规范（Semantic Versioning，SemVer），格式如下：

v<主版本号>.<次版本号>.<补丁号>[-预发布标签]

版本类型	示例	说明
正式版本	v1.2.0	用于生产环境的正式发布版本
Beta 版本	v1.2.0-beta.1	第一个 Beta 测试版本
RC 版本	v1.2.0-rc.1	候选发布版本（Release Candidate）

4.2 Tag 描述说明建议

打 Tag 时，建议使用带注释的 Tag，并附带简洁明确的版本说明，示例如下：

git tag -a v2.0.0 -m "Release v2.0.0: 添加国际化、多语言支持"

• -a 表示创建带注释的 Tag

• -m 后面跟随的是该版本的说明信息，建议包含主要变更点，方便回溯与沟通

五、推荐工作流（基于 Git Flow 简化 + 自动化）🔄

5.1 分支来源与合并目标

开发阶段	分支来源	合并目标	说明
功能开发	develop	develop	日常功能开发，持续集成
Bug 修复	develop	develop	非紧急缺陷修复
热修复	master	master + develop	紧急修复生产环境问题，双向合并
发布准备	develop	release	发布前版本冻结与准备
灰度发布	release	gray	灰度环境部署与验证
正式发布	gray	master	通过灰度验证后正式发布

5.2 PR / MR 流程规范

• 所有代码合并必须通过 Pull Request（PR）或 Merge Request（MR）完成。

• 合并前需至少一名开发人员审核通过。

• 合并提交信息应简洁明了，保证提交历史整洁。

六、CI/CD 与自动化建议（基于 Jenkins）📦

6.1 自动部署策略（推荐）

分支	部署环境	说明
develop	开发环境	持续集成开发版本自动部署
test	测试环境	功能验证与集成测试环境
gray	灰度环境	内部灰度发布与预发布验证
master（打 Tag）	正式环境	正式生产环境部署，仅限打 Tag 时触发

6.2 推荐工具集与 Jenkins 集成建议

功能	工具示例	Jenkins 集成建议
提交校验	Husky + Commitlint	在 Jenkins 构建前通过钩子脚本验证提交规范
自动构建部署	Jenkins Pipeline	采用 Declarative Pipeline 编写自动化流水线，实现构建、测试、部署
代码静态检查	ESLint / Prettier	集成静态代码扫描插件（如 Warnings Next Generation）并生成报告
发布日志生成	standard-version / semantic-release	结合 Jenkins 任务自动生成版本日志，并触发自动发布

6.3 Jenkins 流程示例

1. 触发机制：

   • 监听代码仓库分支推送事件（webhook）

   • Tag 创建触发正式发布流程

   • 手动触发构建

2. 流水线步骤：

   代码拉取 → 提交信息校验 → 代码静态检查 → 单元测试 → 构建 → 部署 → 发布通知

3. 分支策略支持：

   develop、test、gray、master 分支分别配置对应流水线任务或参数化构建

七、常见问题处理建议 📌

问题	说明	建议
忘记切分支开发	直接在 develop 写代码	严格要求功能必须基于 feature/* 分支
提交信息混乱	update code、fix 等	启用 Commitlint 校验，模板统一
主分支误操作	直接 push 到 master	设置分支保护（Require PR、禁用 force push）
多人合并冲突频繁	提交粒度大	频繁同步、提前拉 develop，保持分支短生命周期

---