前端开发 Git 分支与 Tag 管理规范

1.目标

本规范统一团队的分支创建、合并、发布、Tag、回滚和多现场交付方式，确保代码可追溯、版本可复现、现场差异可管理。

2 . 核心约定

1. 仓库长期主干统一使用 master 和 dev

2. 一个需求、缺陷或技术任务对应一个分支，不在同一分支混入无关改动。

3.公共分支禁止直接提交、强制推送和改写历史，只通过 PR/MR 合并。

4.多现场项目从 dev 建立每个现场的长期基线分支，现场定制从对应基线派生。

5.所有正式上线版本必须创建不可移动的 Tag，并记录发布范围和回滚点。

3. 长期公共分支

|--------|----------|----------------------|----------|
| 分支 | 生命周期 | 作用 | 允许合入 |
| master | 长期 | 标准产品生产稳定代码、正式发布基线 | 禁止直接提交 |
| dev | 长期 | 标准产品日常集成、联调和下一版本开发基线 | 禁止直接提交 |

4. 临时工作分支

|---------------|-----------|--------------------|--------------------|
| 分支 类型 | 命名格式 | 作用 | 允许合入 |
| 功能 | feature- | 新功能开发 | 开发完成后合并回 dev |
| 缺陷 | bugfix- | 非紧急 Bug 修复 | 开发完成后合并回 dev |
| 重构 | refactor- | 代码重构/优化 | 开发完成后合并回 dev |
| 发布 | release- | 预发布分支，用于测试和 Bugfix | 发布后合并回 dev |
| 紧急修复 | hotfix- | 紧急修复分支，修复线上问题 | 发布后合并回 dev |
| 现场基线 | site- | 现场长期定制基线 | 只从 dev 拉更新，不合回 dev |

5 .完整迭代开发流程（分阶段 ）

5 .1 版本迭代 标准流程 （release-）

# 1. 切换到dev并拉取最新代码
git checkout dev
git pull origin dev

# 2. 从dev创建本次迭代的分支，推送到远程
git checkout -b release-v2.1.0 dev
git push origin release-v2.1.0

# 3. 开发完成且测试通过后，合并回dev分支，推送到远程
git checkout dev
git pull origin dev
git merge --no-ff release-v2.1.0
git push origin dev

# 4. 合并到 master 分支
git checkout master
git pull origin master
git merge --no-ff dev
git push origin master

# 5. 基于master分支打Tag，Tag推送到远程
git tag -a v2.1.0 -m "发布v2.1.0版本：xxx"
git push origin v2.1.0

# 6. 删除本地和远程的 release-v2.1.0分支（清理）
git branch -d release-v2.1.0
git push origin --delete release-v2.1.0

5 . 2 功能开发 流程（ feature- ）

# 1. 切换到dev并拉取最新代码
git checkout dev
git pull origin dev

# 2. 从dev创建本次迭代的分支，推送到远程
git checkout -b feature-userList
git push origin feature-userList

# 3. 开发完成且测试通过后，合并回dev分支，推送到远程
git checkout dev
git pull origin dev
git merge --no-ff feature-userList
git push origin dev

# 4. 删除本地和远程的 feature-userList分支（清理）
git branch -d feature-userList
git push origin --delete feature-userList

# 5. 后续随下一个 release 分支统一发布到 master

5 . 3 线上紧急修复 (hotfix-)

# 从 master 或线上 Tag 拉分支
git checkout -b hotfix-security master

# 修复、提交
git commit -m "hotfix: 修复安全漏洞"

# 合并到 master 并打补丁 Tag
git checkout master
git merge --no-ff hotfix-security
git tag -a v2.1.1 -m "修复安全漏洞"
git push origin master --tags

# 同步到 dev
git checkout dev
git merge --no-ff hotfix-security

# 删除本地和远程的hotfix分支
git branch -d hotfix-security
git push origin --delete hotfix-security

5 . 4 现场 长期基线分支

# 1. 切换到dev并拉取最新代码
git checkout dev
git pull origin dev

# 2. 从dev创建南沙现场分支，推送到远程
git checkout -b site-nansha
git push origin site-nansha

# 3. 从dev创建花都现场分支，推送到远程
git checkout -b site-huadu
git push origin site-huadu

# 4. 从dev创建增城现场分支，推送到远程
git checkout -b site-zengcheng
git push origin site-zengcheng

# 5. 后续针对该现场的需求，都必须以对应的现场分支为基线创建release-xxx、 feature-xxx 分支，禁止再直接从 dev 分支拉取

6.Tag命名 规范 (视项目定）

#语义化版本格式：v<主>.<次>.<修订>
v2.1.0
v2.1.1
v2.2.0

#release+版本+时间
release-v2.1.0.20260630
release-v2.2.0.20260825

# 在现场基线上打 Tag
nansha-v2.1.0
huadu-v2.1.0
zengcheng-v2.1.0

7. Commit 与 PR/MR 规范

# Commit 格式
<type>(<scope>): <subject>

|----------|--------|-----------------------------|
| type | 含义 | 示例 |
| feat | 新功能 | feat: 新增手机号验证码登录方式 |
| fix | Bug 修复 | fix: 修复金额为 null 时导致页面崩溃的问题 |
| ref | 重构 | ref: 抽取通用的 HTTP 客户端模块 |
| style | 样式/格式化 | style: 修复缩进和代码换行格式 |
| docs | 文档 | docs: 更新安装步骤和使用指南 |
| test | 测试 | test: 添加日期格式转换的单元测试 |
| chore | 构建/工具 | chore: 将 webpack 升级至 5.x 版本 |
| perf | 性能优化 | perf: 实现图片懒加载以提升页面加载速度 |
| ci | CI/CD | ci: 新增测试环境的自动化部署配置 |