---
name: enterprise-git-spec
description: 企业级 Git 分支管理、命名、提交与权限控制规范。当团队需要制定或查阅 Git 协作流程时使用。
---

## 技能概述

本技能提供了一套经过企业实战验证的 Git 协作规范，涵盖分支模型设计、命名约定、提交信息格式以及权限管控四大核心领域。通过遵循本规范，团队能够：

- **降低协作摩擦**：统一的命名和流程让成员快速理解代码状态。
- **保障主干稳定**：通过分支保护和强制评审机制，防止生产事故。
- **实现可追溯性**：规范的提交信息与任务 ID 关联，任何变更均可回溯至需求或缺陷。
- **支撑自动化交付**：规范的提交格式可直接驱动版本号生成与 CHANGELOG 自动发布。

本规范适用于使用 Git 进行源代码管理的中大型项目，尤其适合需要严格管控发布节奏与代码质量的平台型团队。

## 何时使用本技能

|场景|说明|
|---|---|
|**团队建立 Git 规范**|作为团队标准化文档，统一全员协作方式。|
|**新人入职培训**|帮助新成员快速理解团队的代码提交流程和分支策略。|
|**代码评审（Code Review）**|评审人可依据规范检查分支命名、提交信息是否符合要求。|
|**CI/CD 流水线配置**|为自动化工具（如分支保护、Commitlint）提供规则依据。|
|**发布管理**|明确何时创建 `release` 分支，何时启动 `hotfix` 流程。|
|**故障复盘**|通过规范的提交历史快速定位变更引入点与责任人。|

## 1. 分支管理模型 (Branching Model)

团队采用 **简化版 Git Flow** 模型，核心分支永久保护，临时分支按需创建并在合并后及时删除。

| 分支名称 | 生命周期 | 说明 | 创建自 | 合并回 |
| :--- | :--- | :--- | :--- | :--- |
| `main` | 永久 | 生产环境代码，每次合并需打 `Tag` | `release/*`, `hotfix/*` | - |
| `develop` | 永久 | 日常开发集成分支 | `feature/*`, `release/*`, `hotfix/*` | - |
| `feature/*` | 临时 | 新功能开发 | `develop` | `develop` |
| `release/*` | 临时 | 版本发布准备 | `develop` | `main` & `develop` |
| `hotfix/*` | 临时 | 生产环境紧急修复 | `main` | `main` & `develop` |

**流程图：**
```text
Feature ──▶ develop ◀── Release ──▶ Tag ──▶ main
               ▲                          ▲
               └─────── Hotfix ───────────┘
```

## 2. 分支命名规范 (Naming Conventions)

**标准格式：** `<类型前缀>/[任务ID]-<简短描述>-<开发者标识>`

### 命名元素说明
- **类型前缀**（必填）：`feature`, `bugfix`, `hotfix`, `release`
- **任务ID**（推荐）：JIRA/TAPD 编号，如 `PROJ-1234`
- **简短描述**（必填）：全小写英文，单词间用连字符 `-` 连接
- **开发者标识**（推荐）：企业邮箱前缀或拼音，如 `zhangsan`

### 正确与错误示例

| 场景 | ✅ 正确 | ❌ 错误 |
| :--- | :--- | :--- |
| 用户登录功能 | `feature/PROJ-101-user-login-lisi` | `feature_login` |
| 订单金额Bug修复 | `bugfix/PROJ-205-fix-order-amount-wangwu` | `fixBug` |
| 发布 v1.3.0 | `release/v1.3.0` | `release_1.3` |
| 支付回调紧急修复 | `hotfix/payment-callback-error-zhaoliu` | `hotfix-20241001` |

## 3. 提交信息规范 (Commit Message)

强制遵循 **Conventional Commits** 规范，格式如下：

```text
<类型>(<可选范围>): <简短描述>

<可选：详细描述>

<可选：脚注>
```

### 提交类型 (`<类型>`) 枚举

| 类型 | 说明 | 触发版本变更 |
| :--- | :--- | :--- |
| `feat` | 新功能 | 是（次版本号） |
| `fix` | Bug修复 | 是（修订号） |
| `docs` | 文档变更 | 否 |
| `style` | 代码格式调整 | 否 |
| `refactor` | 重构 | 否 |
| `perf` | 性能优化 | 是 |
| `test` | 测试代码 | 否 |
| `chore` | 构建/工具变动 | 否 |
| `ci` | CI配置变更 | 否 |

### 提交示例对比

| 场景 | ✅ 正确 | ❌ 错误 |
| :--- | :--- | :--- |
| 新增短信登录 | `feat(auth): add SMS verification code login` | `update code` |
| 修复首页白屏 | `fix(homepage): resolve white screen on iOS Safari` | `fix bug` |
| 更新API文档 | `docs(api): update user endpoint response examples` | `update doc` |

### MR/PR 自检清单

在发起合并请求时，开发者需确认以下事项：

- [ ] 遵循 Conventional Commits 提交规范
- [ ] 分支命名符合 `类型/ID-描述` 格式
- [ ] 已通过本地代码格式化检查
- [ ] 本地自测通过，无新增明显缺陷
- [ ] 若涉及数据库变更，已提供回滚脚本